레포 **전체** 설계/아키텍처 문서를 작성해, 폐쇄망(에어갭)의 내부 코딩 에이전트와 개발자가 인터넷·외부 문서 없이도 코드베이스를 이해하도록 만든다. 한 기능이 아니라 시스템 전체 — 레이어 구조, 모든 서비스/컴포넌트, 데이터 흐름, 그리고 함께 떠 있는 의존 외부 서버(DB·큐·캐시·오브젝트스토어·모델서버·게이트웨이 등) 토폴로지를 한 장의 지도로 만든다. 사용자가 "이 레포 전체 설계 문서 써줘", "아키텍처/온보딩 문서 만들어줘", "내부 에이전트가 코드베이스 이해하게 정리해줘", "이 시스템이 어떤 서버들에 의존하는지", "새 개발자가 보고 이해할 설계서"를 요청하거나, 에어갭 반입에서 전체 레포가 단위일 때 반드시 사용한다.
How this skill is triggered — by the user, by Claude, or both
Slash command
/repo-design-doc-writer:repo-design-doc-writerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
폐쇄망(에어갭)의 내부 코딩 에이전트는 인터넷·Context7·외부 문서가 없다. 모델
폐쇄망(에어갭)의 내부 코딩 에이전트는 인터넷·Context7·외부 문서가 없다. 모델 사전지식과 레포 자체에 의존하는데, 시스템 전체 지도가 없으면 코드베이스를 제대로 이해하지 못한다 — 무엇이 어디서 돌고, 어떤 외부 서버들에 의존하며, 요청이 어떻게 흐르는지. 이 문서는 그 지도다. 사람도 읽고(개발자 온보딩) 에이전트도 읽는다(오프라인 컨텍스트). 그래서 인터넷 없이도 자립적으로 이해되도록, 그리고 특정 최근 기능에 치우치지 않고 시스템 전체를 균형 있게 작성해야 한다.
가장 자주 빠지는 것: 의존 외부 서버 토폴로지. 코드만 읽으면 "이 앱이 Postgres, Redis, RabbitMQ, 오브젝트스토어, 모델 서버, 게이트웨이에 붙는다"는 그림을 놓친다. 그게 운영·배포·장애의 핵심인데. 그래서 이 스킬은 그 토폴로지를 1급으로 다룬다.
config/env/.env.example)·클라이언트 코드·
배포 매니페스트를 교차 확인해 외부 서버 목록과 각각의 프로토콜·포트·용도·필수여부를
뽑아라.git log/blame/PR로 근거를 캐서 설명하라.
설계서는 "무엇"뿐 아니라 "왜 이렇게"가 있어야 가치 있다.레포 표면 스캔. 매니페스트(pyproject/package.json/go.mod), README, 디렉터리
구조, 엔트리포인트, 설정 모듈, Dockerfile, CI, k8s/compose 매니페스트를 본다.
레이어 경계를 파악(API → 서비스 → 도메인 → 클라이언트 → 영속화 등).
컴포넌트 인벤토리. 모듈/패키지별 책임을 표로. 핵심 추상화(인터페이스/DI)와 구체 구현을 구분.
의존 외부 서버 토폴로지. 설정·클라이언트·배포에서 교차 확인해 표 작성: 서버 / 프로토콜·포트 / 용도 / 필수여부 / 설정 키. (예: 모델 추론서버, DB, 캐시, MQ, 오브젝트스토어, LLM 게이트웨이.) 가능하면 ASCII 토폴로지 다이어그램.
핵심 데이터 흐름. 대표 요청 경로 2~4개를 端到端으로(진입 → 서비스 → 외부서버 → 응답). 동기/비동기 경로를 구분.
횡단 관심사. 설정/시크릿, 인증, 로깅/관측, 동시성/admission, 에러/재시도, 배포/ 롤아웃.
"왜" 복원. 비자명한 결정은 git 히스토리에서 근거를 캐 설명(별도 ADR이 있으면 링크).
설계서 작성. templates/design-doc.md 구조로. 다이어그램·표를 산문보다 우선.
검증. 포트/버전/엔드포인트가 코드·설정과 일치하는지 확인. 미확인은 명시.
docs/design/architecture.md (또는 레포 관례 위치) 하나. 개발자 온보딩과 에이전트
컨텍스트 양쪽에 쓰일 수 있게, 한 문서로 시스템 전체가 보이도록.
템플릿: templates/design-doc.md
- [ ] 레이어/모듈 인벤토리(전체, 한 기능 치우침 없음)
- [ ] 의존 외부 서버 토폴로지 표 + 다이어그램(프로토콜·포트·용도·필수여부)
- [ ] 대표 데이터 흐름 2~4개(동기/비동기 구분)
- [ ] 횡단 관심사(설정/인증/관측/동시성/배포)
- [ ] 비자명 구조의 "왜"를 git에서 복원
- [ ] 포트/버전/엔드포인트 코드·설정과 일치 확인(미확인은 명시)
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub junnystateofmind/airgap-repo-design-doc-writer --plugin repo-design-doc-writer