전문가용 시작
이 매뉴얼은 MV3 manifest를 손본 적 있고, TypeScript와 React가 일상이고, Claude Code 또는 Codex로 코드를 맡겨본 적 있는 독자를 가정합니다. FSD라는 이름은 들어봤다는 정도면 충분합니다. 6레이어 의존 방향과 메시지 라우팅은 다음 섹션 architecture에서 풀어냅니다.
여기서 다루는 것은 reference 명령이 아니라 “왜 이 모양인지”입니다. 뼈대가 왜 이렇게 잡혔는지 한 번 통과한 다음 architecture로 넘어가야 그 뒤 build-and-package와 distribution이 의미 있게 읽힙니다.
풀려는 문제 한 줄
섹션 제목: “풀려는 문제 한 줄”AI에게 확장 프로그램을 맡기면 첫 두세 프롬프트는 멀쩡하게 나옵니다. 그다음부터 구조가 흔들립니다. 같은 기능이 두세 군데에 따로 생기고, 초기에 왜 이렇게 정했는지가 세션 사이로 날아갑니다. chrome-ext-base는 그 자리에 guardrail을 박아둔 출발점입니다.
guardrail 세 개
섹션 제목: “guardrail 세 개”FSD와 eslint-plugin-boundaries
섹션 제목: “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 습관
섹션 제목: “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 사이 메시지가 어떻게 라우팅되는지, 어댑터 전략이 호출 코드에서 어떻게 보이는지를 다이어그램과 함께 봅니다.