전문가용 시작

이 매뉴얼은 MV3 manifest를 손본 적 있고, TypeScript와 React가 일상이고, Claude Code 또는 Codex로 코드를 맡겨본 적 있는 독자를 가정한다. FSD라는 이름은 들어봤다는 정도면 충분하다. 6레이어 의존 방향과 메시지 라우팅은 다음 섹션 architecture에서 풀어낸다.

여기서 다루는 것은 reference 명령이 아니라 "왜 이 모양인지"다. 뼈대가 왜 이렇게 잡혔는지 한 번 통과한 다음 architecture로 넘어가야 그 뒤 build-and-package와 distribution이 의미 있게 읽힌다.

풀려는 문제 한 줄

AI에게 확장 프로그램을 맡기면 첫 두세 프롬프트는 멀쩡하게 나온다. 그다음부터 구조가 흔들린다. 같은 기능이 두세 군데에 따로 생기고, 초기에 왜 이렇게 정했는지가 세션 사이로 날아간다. chrome-ext-base는 그 자리에 guardrail을 박아둔 출발점이다.

guardrail 세 개

FSD와 eslint-plugin-boundaries

폴더 구조는 Feature-Sliced Design을 따르고, eslint-plugin-boundaries가 빌드 타임에 import 방향을 강제한다. AI가 임의로 레이어를 가로지르면 빌드가 깨진다. 그것만으로 모델이 한참 줄을 선다.

메시지 타입 단일 파일

shared/lib/messaging/messages.ts 한 장에 모든 메시지 타입을 모은다. content script와 background, popup 사이로 오가는 모든 페이로드는 여기에 정의된 discriminated union을 통과해야 한다. 새 메시지가 생길 때 다른 파일을 만들고 싶은 충동을 한 번에 막아둔다.

백엔드 어댑터

shared/api/backend/에 어댑터 전략이 들어있다. console-log 모드는 콘솔에 페이로드만 찍고 끝낸다. supabase-direct는 Supabase로 바로 쏘고, server-relay는 자체 서버를 거친다. 모드 전환은 옵션 페이지에서 하고, 호출하는 쪽은 어떤 모드인지 모르고 동작한다. 백엔드가 정해지지 않은 단계에서 UI 작업을 시작할 수 있다는 게 이 어댑터의 본 목적이다.

ADR 습관

되돌리기 비싼 결정은 docs/adr/에 한 장씩 쌓는다. permission을 왜 좁혔는지, sidePanel을 왜 popup 대신 골랐는지, 어댑터 인터페이스를 왜 이 모양으로 잡았는지. 코드는 무엇을 했는지를 보여주고, ADR은 왜 그랬는지를 보여준다. 다음 세션 또는 다음 사람이 들어왔을 때 결과만 보고 의도를 거꾸로 추론하는 비용을 아낀다.

ADR 양식과 작성 시점은 docs/adr/README.md에 짧게 정리돼 있다.

자동화 진입점은 한 곳을 가리킨다

Claude Code 쪽 진입점은 .claude/agents/와 .claude/skills/. Codex 쪽 진입점은 루트의 AGENTS.md. 두 경로 모두 결국 같은 파일 하나를 읽는다.

AI_AUTOMATION.md. 도메인 규칙, FSD 슬라이스 매핑, MV3 금기 패턴, 6차원 리뷰 체크리스트, Phase 흐름이 전부 여기 모여있다. 두 자동화 도구의 진입점이 한 canonical 문서를 공유하기 때문에, Claude Code에서 잡힌 결정이 Codex 세션에서도 그대로 통한다.

지금 빠져 있는 것

이 base는 솔직히 미완성인 부분이 있다. 매뉴얼과 랜딩은 public이지만, 템플릿 자체는 상업 라이선스 모델이다. 그런데 결제 흐름과 구매자 webhook이 아직 안 붙었다. COMMERCIAL-LICENSE.md도 초안 상태고 변호사 검토가 안 끝났다. 실제 판매 전에는 둘 다 마무리돼야 한다.

기술 쪽에서도 빠진 자리가 있다. 첫 실행을 좀 더 매끄럽게 다듬고 싶은 zero-config 모드, 권한 변경을 도와주는 마이그레이션 스킬, 자동 업데이트용 update.xml 템플릿. 이 매뉴얼은 빠진 자리를 숨기지 않고 distribution 섹션에서 그대로 적어둔다.

이 매뉴얼이 가정하지 않는 것

OS별 설치 분기, Node 버전 매니저 선택, 터미널이 처음인 사람을 위한 단계별 안내는 여기 없다. 그쪽이 필요하면 비개발자용 매뉴얼을 본다. 같은 base를 다른 호흡으로 푼 짝이다.

다음

다음은 architecture. FSD 6레이어가 어떤 의존 방향으로 묶여있는지, content script와 background와 popup 사이 메시지가 어떻게 라우팅되는지, 어댑터 전략이 호출 코드에서 어떻게 보이는지를 다이어그램과 함께 본다.