NotionNext 문서

Appearance

AI를 활용해 NotionNext 개발하기 ​

이전 문서: AI를 활용해 NotionNext 개발하기 게시일: 2025-4-25 마지막 수정: 2026-5-2 원래 분류: ⌨ 개발 튜토리얼

머리말 ​

프로그래밍 언어를 전혀 모르는 상태에서도 새 테마를 커스터마이징할 수 있을까요?

결론부터 말하면 가능합니다. 다만 쉽지는 않습니다. 특정 업계에 대한 고객 경험과 제품 경험이 전혀 없는 상태에서 곧바로 그 업계의 회사를 여는 것과 비슷합니다. 그래도 AI를 활용해 스스로 학습하고 파고드는 데 익숙하다면 분명 도움이 됩니다.

클라우드 환경 ​

먼저 관련 문서를 읽어 보기를 권장합니다. 그 문서에는 NotionNext 프로젝트를 개발할 때 필요한 기본 지식이 소개되어 있습니다.

GitHub Codespaces ​

GitHub는 자체적으로 Codespaces 클라우드 환경을 제공합니다. 간단히 말해 GitHub 저장소에서 Code를 클릭한 뒤 Create codespace를 클릭하면 클라우드 개발 환경을 열 수 있습니다. 더하기 버튼에서 새 클라우드 개발 공간을 만들 수도 있습니다.

28f32ba842c3ed98116d7a6e2ad5c29.png

Codespace 클라우드 공간의 화면은 로컬에서 사용하는 VS Code와 비슷합니다. 상단 오른쪽의 Copilot 아이콘을 클릭하면 AI와 대화할 수 있습니다.

image.png

Copilot은 현재 열려 있는 파일을 실시간으로 참고합니다. 대화를 통해 파일 수정이나 제안을 받을 수 있습니다.

Google Firebase Studio ​

Google은 Firebase Studio를 출시했습니다. GitHub 프로젝트를 이 클라우드 환경으로 가져와 개발할 수 있으며, 원리는 GitHub Codespaces와 비슷합니다.

다만 Firebase Studio는 인터페이스 현지화가 제한적이라 사용 난도가 조금 있을 수 있습니다. 또한 Gemini의 AI 사용량과 개발 특화 경험은 Copilot만큼 안정적이지 않을 수 있습니다. Copilot은 GitHub와 VS Code 사용자 기반을 바탕으로 프로그래밍에 특화되어 있습니다.

image.png

그래서 저는 클라우드 개발 환경으로 Codespaces를 권장합니다. GitHub와의 통합이 더 좋고 Copilot의 AI 성능도 더 강합니다.

Firebase를 사용한 AI 개발 예시 ​

아래 링크를 클릭해 Firebase에 접속하고 가입합니다.

https://studio.firebase.google.com/

image.png

프로젝트 홈으로 이동해 ImportRepo를 선택합니다.

image.png

GitHub 저장소 주소를 입력하면 됩니다.

image.png

Firebase는 프로젝트 코드를 자동으로 가져오고 환경 설치를 진행합니다.

image.png

설치가 끝나면 코드가 다음처럼 표시됩니다.

image.png

테마 커스터마이징 ​

여기서는 Firebase로 시연하지만 Codespaces 사용 방법도 거의 같습니다.

테마 폴더 복사 ​

기존 테마를 직접 수정하는 것은 권장하지 않습니다. 이후 원본 테마도 함께 수정되면 업데이트 과정에서 충돌이 많이 생길 수 있습니다.

themes 디렉터리에서 마음에 드는 테마 또는 새로 만들려는 테마 구조와 비슷한 테마를 찾습니다. 예를 들어 example 테마 폴더를 사용할 수 있습니다. 각 테마의 보충 설명은 저장소의 docs/themes를 참고하세요. Fuwari, Claude 등이 포함되어 있습니다. 오른쪽 클릭 후 copy로 이 폴더를 복사합니다.

image.png

그다음 themes 폴더를 오른쪽 클릭하고 paste를 선택해 붙여 넣습니다.

image.png

붙여 넣으면 새 폴더가 생깁니다. 여기서는 example 폴더를 복사했으므로 새 폴더 이름은 example copy가 됩니다.

image.png

테마 이름 변경 ​

새 테마 이름을 dream으로 만들고 싶다고 가정합니다. example copy 폴더를 오른쪽 클릭하고 rename을 선택한 뒤 새 폴더 이름을 입력하고 Enter를 누르면 됩니다.

image.png

image.png

테마 내용 수정 ​

dream / index.js 파일을 더블 클릭해 열고, 이 파일을 첨부 형태로 대화에 추가합니다. Gemini 채팅 창 아래의 첨부 버튼을 클릭한 뒤 file을 선택합니다.

image.png

팝업 파일 선택 창에서 현재 index.js 파일을 선택합니다.

image.png

Copilot을 사용한다면 이 단계는 생략해도 됩니다.

그다음 Gemini에 다음처럼 요청합니다.

이 테마의 상단 내비게이션 바가 어디에 있는지, 어떤 파일인지 알려 주세요. 그리고 이 내비게이션 바를 수정해 왼쪽에 파란색 텍스트 한 줄을 추가해 주세요. 내용은 "새 테마 dream 생성 성공"입니다. 파일은 /themes/dream/components 디렉터리 아래에 있을 것입니다.

그러면 AI가 관련 내용을 설명하고 코드 수정 제안을 제공합니다.

image.png

제안 상자 오른쪽의 Review changes를 클릭하면 수정 내용을 검토할 수 있습니다. 왼쪽의 Updates file을 클릭하면 파일이 자동으로 수정됩니다.

프로젝트 실행 ​

프로젝트를 실행하기 전에 현재 테마를 방금 만든 dream 테마로 전환할 수 있습니다. 가장 간단한 방법은 blog.config.js 파일을 수정하는 것입니다.

image.png

콘솔에 npm run dev를 입력해 프로젝트를 실행합니다.

image.png

실행 후 키보드 Ctrl 키를 누른 상태에서 콘솔에 출력된 http://localhost:3000을 마우스로 클릭하면 실시간 디버깅 페이지를 열 수 있습니다.

image.png

Firebase는 디버깅 페이지에 접근할 수 있는 임시 URL을 자동으로 할당합니다.

image.png

열어 보면 방금 수정한 내용이 이미 적용된 것을 확인할 수 있습니다. 이후 코드 수정은 모두 이 페이지에 실시간으로 반영됩니다.

방금 편집하던 페이지로 돌아가 내용을 직접 수정해 보겠습니다.

image.png

다시 페이지를 보면 수정이 적용되어 있습니다.

image.png

이제 AI와 계속 대화하면서 무엇을 바꿀지 알려 주고, 결과를 받은 뒤 파일 업데이트를 클릭하면 됩니다.

코드 저장 ​

모든 코드는 Git 저장소에 커밋해야 저장됩니다. 여기에는 Git 사용법이 포함됩니다. Git은 대규모 다인 협업을 위해 설계된 강력한 도구라 어느 정도 학습이 필요합니다. 여기서는 가장 간단한 코드 커밋 과정을 시연합니다.

왼쪽의 Source Control 아이콘을 클릭합니다.

image.png

이번에 변경된 내용이 모두 표시됩니다. 저장하려는 변경 내용을 확인해야 합니다.

image.png

각 파일 오른쪽에 마우스를 올리면 더하기 버튼이 나타납니다. 클릭하면 해당 파일을 Git 저장소에 저장 대상으로 올립니다.

image.png

클릭한 파일은 Staged Changes 영역 아래에 표시됩니다.

image.png

Changes 오른쪽의 더하기 버튼을 클릭해 모든 파일을 한 번에 올릴 수도 있습니다.

image.png

커밋할 파일을 확인한 뒤, 상단의 Message 입력란에 이번 커밋의 기능 설명을 작성합니다. 필수 항목이며 나중에 이번 커밋 내용을 확인하는 데 도움이 됩니다. 예를 들어 여기서는 "새 테마 dream 생성"이라고 입력합니다.

image.png

설명을 입력한 뒤 아래의 commit 버튼을 클릭해 커밋합니다. 커밋 후에는 아래 목록이 비어 있습니다. 더 이상 확인하거나 커밋할 내용이 없기 때문입니다.

image.png

여기 버튼 하나가 보입니다. 새 Git 브랜치를 만들었다면 위쪽에 Publish branch 버튼이 표시됩니다. 기존 브랜치, 예를 들어 main 브랜치에서 개발 중이라면 sync changes가 표시됩니다. GitHub 클라우드 저장소와 동기화가 필요하다는 뜻입니다.

image.png

이 버튼을 클릭해 내용을 GitHub 클라우드에 동기화합니다.

GitHub 권한 부여 ​

GitHub가 제공하는 Codespaces 환경을 사용한다면 아래 단계는 필요하지 않습니다.

여기서 처음 동기화하는 경우 GitHub 플러그인 권한을 요청합니다. 동의하면 됩니다.

image.png

그러면 인증 코드가 표시됩니다. copy & continue to github를 클릭합니다.

image.png

자동으로 이동한 페이지에 인증 코드를 붙여 넣거나 입력합니다.

image.png

그다음 2차 확인 페이지에서 Authorize Visual Studio Code를 클릭합니다.

image.png

image.png

위 단계가 잘 진행되지 않는다면 Firebase는 GitHub token을 사용한 커밋 인증도 지원합니다. 다른 선택지이지만 보통은 필요하지 않으므로 여기서는 자세히 다루지 않습니다.

image.png

코드 커밋과 동기화 완료 ​

이제 Source Control 페이지를 다시 보면 커밋 대기, 검토 대기, 동기화 대기 작업이 없습니다.

image.png

GitHub 프로젝트에서는 방금 작성한 커밋 기록 설명과 해당 파일 내용을 확인할 수 있습니다.

image.png

이후 Vercel은 코드 변경을 자동으로 감지하고 사이트를 자동으로 배포합니다.

여기까지가 클라우드 환경과 AI를 활용해 작은 기능을 개발하고 GitHub에 동기화하는 전체 흐름입니다.

마무리 ​

주의할 점은 AI와 클라우드 환경이 어디까지나 효율 도구라는 것입니다. 본질적으로는 모르는 사람이 빠르게 입문하고, 이미 아는 사람이 개발 시간을 절약하도록 돕는 역할입니다. 개발을 완전히 익히려면 NotionNext가 사용하는 프레임워크 기술과 파일 디렉터리 구조도 함께 학습해야 합니다.

앞으로 몇 년 뒤 AI Agent가 보편화되면 위와 같은 복잡한 단계가 필요 없을 수도 있습니다. 그때는 명령만 내리면 되고, 구현 방식은 Agent가 고민하게 될 것입니다.

원문 링크 ​

https://docs.tangly1024.com/article/notion-next-develop-with-ai