repo-design-doc-writer

airgap-repo-design-doc-writer

레포 전체 설계/아키텍처 문서 작성기 — 폐쇄망 환경에서 인터넷 없이 코드베이스를 이해하기 위해

🎯 개요

이 스킬은 레포지토리 전체의 설계서와 아키텍처 문서를 자동으로 작성합니다. 폐쇄망 환경에 배치된 AI 코딩 에이전트나 개발자가 인터넷·외부 문서 없이도 코드베이스를 온전히 이해할 수 있도록 만든 것이 핵심 목표입니다.

단순히 코드만 나열하는 게 아닙니다. 시스템 전체의 레이어 구조, 모든 서비스/컴포넌트, 데이터 흐름, 그리고 외부 서버(DB, 큐, 캐시, 오브젝트 스토어, 모델 서버, 게이트웨이 등) 토폴로지까지 한 장의 문서로 정리합니다.

✨ 주요 기능

• 시스템 전체 균형 분석 — 최근 커밋이나 특정 기능에 치우치지 않고 레이어/모듈 전반을 훑어 분석
• 의존 외부 서버 매핑 — 설정·클라이언트 코드·배포 매니페스트를 교차 확인해 프로토콜·포트·용도·필수여부 모두 표기
• ASCII 토폴로지 다이어그램 — 앱과 외부 서버들의 연결 관계를 시각적으로 표현
• 핵심 데이터 흐름 추적 — 대표 요청 경로 2~4개를 끝에서 끝까지 추적, 동기/비동기 경로 구분
• "왜" 복원 — 비자명한 구조 결정을 git log/blame/PR 히스토리에서 근거를 찾아 설명
• 검증된 사실만 — 포트·버전·엔드포인트는 코드·설정·lockfile에서 직접 확인, 추측은 추측으로 명시

📦 설치

Claude Marketplace (Claude Code)

Claude Code에서 @marketplace로 설치합니다:

@marketplace junnystateofmind/airgap-repo-design-doc-writer

설치 후 Claude Code 세션에서 바로 사용할 수 있습니다.

Hermes Agent 스킬로 설치

hermes skills install https://github.com/junnystateofmind/airgap-repo-design-doc-writer

수동 설치

이 레포를 clone해서 ~/.hermes/skills/에 배치하면 됩니다.

cd ~/.hermes/skills
git clone https://github.com/junnystateofmind/airgap-repo-design-doc-writer.git repo-design-doc-writer

🚀 사용법

메시지로 요청하면 끝입니다:

요청 예시	설명
"이 레포 전체 설계 문서 써줘"	전체 아키텍처 문서 생성
"아키텍처/온보딩 문서 만들어줘"	개발자 온보딩용 문서
"내부 에이전트가 코드베이스 이해하게 정리해줘"	에어갭 에이전트용 문서
"이 시스템이 어떤 서버들에 의존하는지"	외부 서버 토폴로지 중심 분석
"새 개발자가 보고 이해할 설계서"	온보딩 관점의 문서

📁 프로젝트 구조

airgap-repo-design-doc-writer/
├── SKILL.md                      # 메인 스킬 파일 (워크플로우, 원칙, 체크리스트)
├── templates/
│   └── design-doc.md             # 설계서 작성 템플릿
├── agents/
│   └── openai.yaml               # OpenAI/Codex 인터페이스 정의
└── .claude-plugin/
    ├── plugin.json               # Claude Code 플러그인 매니페스트
    └── marketplace.json          # Claude Code Marketplace 등록 정보

📋 작성 프로세스

1. 레포 표면 스캔 — 매니페스트, README, 디렉터리 구조, 엔트리포인트, 설정, Dockerfile, CI, k8s/compose 확인
2. 컴포넌트 인벤토리 — 모듈/패키지별 책임을 표로 정리
3. 의존 외부 서버 토폴로지 — 설정·클라이언트·배포에서 교차 확인하여 외부 서버 목록 추출
4. 핵심 데이터 흐름 — 대표 요청 경로 2~4개를 끝에서 끝까지 추적
5. 횡단 관심사 — 설정/시크릿, 인증, 로깅/관측, 동시성, 에러/재시도, 배포/롤아웃
6. "왜" 복원 — 비자명한 결정의 근거를 git 히스토리에서 캐서 설명
7. 설계서 작성 — templates/design-doc.md 구조로 산출물 생성
8. 검증 — 포트/버전/엔드포인트가 코드·설정과 일치하는지 확인

📝 산출물

docs/design/architecture.md (또는 레포 관례 위치)에 설계서가 작성됩니다. 개발자 온보딩과 에이전트 컨텍스트 양쪽에 쓰일 수 있게, 한 문서로 시스템 전체가 보이도록 작성합니다.

✅ 완료 체크리스트

• 레이어/모듈 인벤토리 (전체, 한 기능 치우침 없음)
• 의존 외부 서버 토폴로지 표 + 다이어그램 (프로토콜·포트·용도·필수여부)
• 대표 데이터 흐름 2~4개 (동기/비동기 구분)
• 횡단 관심사 (설정/인증/관측/동시성/배포)
• 비자명 구조의 "왜"를 git에서 복원
• 포트/버전/엔드포인트 코드·설정과 일치 확인 (미확인은 명시)

🎨 작성 원칙

• 시스템 전체를 균형 있게 — git 최근 커밋이나 한 기능에 끌려가지 않음
• 의존 서버를 빠짐없이 매핑 — 설정·클라이언트·배포를 교차 확인
• "왜"를 git에서 — 비자명한 구조는 git log/blame/PR로 근거 캐서 설명
• 검증된 사실만 — 포트·버전·엔드포인트는 코드/설정/lockfile에서 확인

🛠 필요 조건

• git — 히스토리 분석용
• Hermes Agent 또는 Claude Code — 스킬 실행용
• 분석 대상 레포지토리에 접근 가능한 권한

📄 라이선스

[ 라이선스 파일 확인 ]

👤 작성자

junny — junnystateofmind

💡 관련 스킬

• claude-digest — 다중 서버 Claude Code 세션 수집 및 다이제스트 생성