전문가용 시작
이 매뉴얼은 MV3 manifest를 손본 적 있고, TypeScript와 React가 일상이고, Claude Code 또는 Codex로 코드를 맡겨본 적 있는 독자를 가정합니다. FSD라는 이름은 들어봤다는 정도면 충분합니다. 6레이어 의존 방향과 메시지 라우팅은 다음 섹션인 architecture에서 설명합니다.
여기서 다루는 것은 참고용 명령이 아니라 “왜 이 구조인지”입니다. 뼈대가 왜 이렇게 잡혔는지를 한 번 이해한 다음 architecture로 넘어가야 그 뒤의 build-and-package와 distribution이 의미 있게 읽힙니다.
풀려는 문제 한 줄
섹션 제목: “풀려는 문제 한 줄”AI에게 확장 프로그램을 맡기면 첫 두세 프롬프트는 멀쩡하게 나옵니다. 그다음부터는 구조가 일관성을 잃습니다. 같은 기능이 두세 군데에 따로 생기고, 초기에 왜 이렇게 정했는지가 세션이 바뀌는 사이에 사라집니다. chrome-ext-base는 그런 지점에 안전장치를 걸어 둔 출발점입니다.
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 금기 패턴, 여섯 관점 리뷰 체크리스트, Phase 흐름이 전부 여기 모여 있습니다. 두 자동화 도구의 진입점이 같은 기준 문서 하나를 공유하기 때문에, Claude Code에서 내린 결정이 Codex 세션에서도 그대로 적용됩니다.
지금 빠져 있는 것
섹션 제목: “지금 빠져 있는 것”이 base는 솔직히 미완성인 부분이 있습니다. 매뉴얼과 랜딩 페이지는 공개돼 있지만, 템플릿 자체는 상업 라이선스 모델입니다. 그런데 결제 흐름과 구매자 webhook이 아직 연결되지 않았습니다. COMMERCIAL-LICENSE.md도 초안 상태이고 변호사 검토가 끝나지 않았습니다. 실제 판매 전에는 둘 다 마무리돼야 합니다.
기술 쪽에도 빠진 것이 있습니다. 첫 실행을 좀 더 매끄럽게 다듬어 줄 zero-config 모드, 권한 변경을 도와주는 마이그레이션 스킬, 자동 업데이트용 update.xml 템플릿이 그렇습니다. 이 매뉴얼은 빠진 것을 숨기지 않고 distribution 섹션에 그대로 적어 둡니다.
이 매뉴얼이 가정하지 않는 것
섹션 제목: “이 매뉴얼이 가정하지 않는 것”OS별 설치 분기, Node 버전 매니저 선택, 터미널이 처음인 사람을 위한 단계별 안내는 여기에 없습니다. 그쪽이 필요하면 비개발자용 매뉴얼을 봅니다. 같은 base를 다른 방식으로 설명한 한 쌍입니다.
다음 섹션은 architecture입니다. FSD 6레이어가 어떤 의존 방향으로 묶여 있는지, content script와 background와 popup 사이의 메시지가 어떻게 라우팅되는지, 어댑터 전략이 호출 코드에서 어떻게 보이는지를 다이어그램과 함께 봅니다.