repo-design-doc-writer

전체 레포 설계 문서 작성기

왜 필요한가

폐쇄망(에어갭)의 내부 코딩 에이전트는 인터넷·Context7·외부 문서가 없다. 모델 사전지식과 레포 자체에 의존하는데, 시스템 전체 지도가 없으면 코드베이스를 제대로 이해하지 못한다 — 무엇이 어디서 돌고, 어떤 외부 서버들에 의존하며, 요청이 어떻게 흐르는지. 이 문서는 그 지도다. 사람도 읽고(개발자 온보딩) 에이전트도 읽는다(오프라인 컨텍스트). 그래서 인터넷 없이도 자립적으로 이해되도록, 그리고 특정 최근 기능에 치우치지 않고 시스템 전체를 균형 있게 작성해야 한다.

가장 자주 빠지는 것: 의존 외부 서버 토폴로지. 코드만 읽으면 "이 앱이 Postgres, Redis, RabbitMQ, 오브젝트스토어, 모델 서버, 게이트웨이에 붙는다"는 그림을 놓친다. 그게 운영·배포·장애의 핵심인데. 그래서 이 스킬은 그 토폴로지를 1급으로 다룬다.

작성 원칙

• 시스템 전체를 균형 있게. git 최근 커밋이나 한 기능에 끌려가지 마라. 레이어/모듈 전반을 훑어 대표성 있게 다룬다.
• 의존 서버를 빠짐없이 매핑. 설정(config/env/.env.example)·클라이언트 코드· 배포 매니페스트를 교차 확인해 외부 서버 목록과 각각의 프로토콜·포트·용도·필수여부를 뽑아라.
• "왜"를 git에서. 비자명한 구조는 git log/blame/PR로 근거를 캐서 설명하라. 설계서는 "무엇"뿐 아니라 "왜 이렇게"가 있어야 가치 있다.
• 검증된 사실만. 포트·버전·엔드포인트는 코드/설정/lockfile에서 확인. 추측은 추측으로 표기.

워크플로우

1. 레포 표면 스캔. 매니페스트(pyproject/package.json/go.mod), README, 디렉터리 구조, 엔트리포인트, 설정 모듈, Dockerfile, CI, k8s/compose 매니페스트를 본다. 레이어 경계를 파악(API → 서비스 → 도메인 → 클라이언트 → 영속화 등).

2. 컴포넌트 인벤토리. 모듈/패키지별 책임을 표로. 핵심 추상화(인터페이스/DI)와 구체 구현을 구분.

3. 의존 외부 서버 토폴로지. 설정·클라이언트·배포에서 교차 확인해 표 작성: 서버 / 프로토콜·포트 / 용도 / 필수여부 / 설정 키. (예: 모델 추론서버, DB, 캐시, MQ, 오브젝트스토어, LLM 게이트웨이.) 가능하면 ASCII 토폴로지 다이어그램.

4. 핵심 데이터 흐름. 대표 요청 경로 2~4개를 端到端으로(진입 → 서비스 → 외부서버 → 응답). 동기/비동기 경로를 구분.

5. 횡단 관심사. 설정/시크릿, 인증, 로깅/관측, 동시성/admission, 에러/재시도, 배포/ 롤아웃.

6. "왜" 복원. 비자명한 결정은 git 히스토리에서 근거를 캐 설명(별도 ADR이 있으면 링크).

7. 설계서 작성. templates/design-doc.md 구조로. 다이어그램·표를 산문보다 우선.

8. 검증. 포트/버전/엔드포인트가 코드·설정과 일치하는지 확인. 미확인은 명시.

산출물

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

템플릿: templates/design-doc.md

완료 체크리스트

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