/docs-architecture

name: docs-architecture
description: "아키텍처 문서 생성/갱신 — ARCHITECTURE.md(코드맵), 아키텍처 구성도(C4 mermaid), ADR(MADR), 데이터 모델 ERD. 아키텍처 문서/구성도 작성·갱신, ADR 기록, ERD/데이터 모델 문서화, 구조적 리팩토링 후 문서 반영이 필요할 때. API 명세는 docs-interfaces, 사용자/운영 매뉴얼은 docs-manuals, 코드 구현에는 사용하지 않음"
user-invocable: true
disable-model-invocation: false
allowed-tools: Read, Write, Edit, Glob, Grep, Bash

아키텍처 문서 스킬

프로젝트의 구조적 사실을 문서화한다. 산출물은 `docs/` 아래, 다이어그램은 mermaid(레포에서 네이티브 렌더).

입력

$ARGUMENTS

산출물 선택 (결정 트리)

| 상황 | 산출물 | |------|--------| | 소규모 프로젝트(<10k LOC) | README 아키텍처 섹션 + 컨텍스트 다이어그램 1개면 충분 — 과잉 문서화 금지 | | 기여자가 길을 잃는 규모 | `docs/ARCHITECTURE.md` (코드맵) | | 시스템 경계/외부 연동 설명 필요 | C4 Context + Container 다이어그램 | | 중요한 설계 결정 발생 | `docs/design-docs/ADR-NNN-[제목].md` (MADR) | | 영속 데이터 구조 변경 | `docs/ARCHITECTURE.md` 내 ERD 섹션 또는 `docs/data-model.md` | | 대규모/규제 시스템 | arc42 12섹션 문서 (명시 요청 시에만) |

ARCHITECTURE.md 작성 규칙 (코드맵)

1. **지도이지 지도책이 아니다** — 굵직한 모듈과 관계만. 파일별 나열 금지 2. 먼저 "이 시스템이 푸는 문제"를 조감, 그다음 코드맵 3. 중요 심볼은 이름만 언급, 하이퍼링크 금지 (링크는 썩는다 — 독자는 심볼 검색을 쓴다) 4. **아키텍처 불변식**을 명시 (예: "domain 레이어는 infra를 import하지 않는다") 5. 코드를 읽으면 아는 것은 쓰지 않는다 — 구조만으로 알 수 없는 결정/이유를 쓴다

구조:

# Architecture

## 개요        ← 시스템이 푸는 문제, 1-2문단
## 구성도      ← C4 Context/Container mermaid
## 코드맵      ← 모듈별 역할 + 경계 (디렉토리 ≈ 문단 1개)
## 불변식      ← 지켜야 할 구조 규칙
## 크로스커팅  ← 로깅, 에러 처리, 인증 등 공통 관심사

다이어그램

mermaid 문법과 관례는 `references/mermaid-conventions.md` 참조 (C4Context/C4Container, sequenceDiagram, erDiagram, architecture-beta).

핵심 관례:

• 다이어그램 1개 = 관심사 1개, 노드 15-20개 이하
• C4는 Context → Container 2레벨까지가 기본. Component 레벨은 flowchart + subgraph가 더 잘 그려짐
• 인프라/배포 토폴로지는 `architecture-beta` 우선

ADR (MADR 형식)

• 위치: `docs/design-docs/ADR-NNN-[kebab-제목].md` — 번호는 3자리 제로패딩 (예: `ADR-001-use-postgres.md`), `docs/design-docs/index.md`에 인덱스 갱신
• 템플릿: `templates/adr.md` (기본은 minimal — Context/Decision/Consequences. 논쟁적 결정만 full MADR)
• **ADR은 불변** — 뒤집을 땐 새 ADR로 supersede, 기존 문서 수정 금지
• status: proposed → accepted → superseded by ADR-NNN

실행 절차

1. 대상 파악: 인자 없으면 `git diff --name-only HEAD~5..HEAD` + 프로젝트 구조 스캔으로 변경된 구조 요소 탐지 2. 기존 `docs/ARCHITECTURE.md`가 있으면 Edit로 갱신 (전면 재작성 금지 — 변경된 섹션만) 3. 다이어그램의 노드가 실제 코드 구조와 일치하는지 확인 후 생성 4. `docs/docs.yaml` 매니페스트 갱신 (없으면 생성):

   docs:
     - path: docs/ARCHITECTURE.md
       covers: ["src/**", "!src/**/*.test.*"]
       last_reviewed: 2026-07-27

5. 설명은 한국어, 코드/식별자는 원문

제약

• `docs/` 폴더만 수정. 소스 코드 수정 금지
• 추측으로 다이어그램을 그리지 않는다 — 코드에서 확인한 관계만