문제: 구조 정리로 저장소 루트에 `compose/`(개발 compose의 보조 파일)가 생겼다. 참조 검사는 `src/`, `docs/`, `scripts/`, `infra/`, `.github/`로 시작하는 인라인 코드만 본다. 그래서 살아 있는 문서가 가리키는 `compose/redis/acl/README.md` 같은 경로는 파일이 옮겨지거나 지워져도 걸리지 않는다. 지금 살아 있는 문서 여덟 개가 `compose/` 경로를 쓴다. 고친 방법: PATH_ROOTS에 `compose/`를 더한다. 정본 design-docs `conventions/docs-system.md` K3는 「repo 경로」 전체를 말하고 접두사 목록을 정하지 않으므로 규칙 변경이 아니라 새 루트 폴더를 적용한 것이다. 지운 `infra/`는 남겨 둔다(다시 쓰이면 낡은 참조로 걸린다). 루트 파일 (`compose.yaml` 등)은 지금처럼 보지 않는다. 위험·한계: 새로 걸린 참조는 없다(지금 트리의 `compose/` 참조는 모두 있다). 검증: 새 시험 `test_a_missing_path_under_the_root_compose_folder_fails`가 고치기 전 실패(RED: 오류 목록이 비어 있음), 고친 뒤 43개 모두 통과. check-docs.py rc=0(참조 걸림 7·예외 7).
148 lines
10 KiB
Markdown
148 lines
10 KiB
Markdown
# docs
|
|
|
|
저장소의 모든 문서는 이 디렉터리 아래에 있다. 규칙은 둘이다: 어떤 문서를 어디에 두는지(아래 표),
|
|
문서의 수명에 따라 무엇을 어떤 언어로 고치는지(「문서 수명과 언어」). 파일 목록은 디렉터리를 직접 읽는다.
|
|
개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.
|
|
|
|
## 어댑터별 운영 문서
|
|
|
|
각 어댑터의 지원 범위, 설정, 보안, 운영, 마이그레이션 문서다. 코드와 함께 갱신되어야 하는 문서이고,
|
|
`docs/httpclient/` 는 `scripts/verify-httpclient-docs.py` 가 코드에서 뽑은 이름과 대조한다.
|
|
|
|
| 디렉터리 | 대상 |
|
|
| --- | --- |
|
|
| `fileserver/` | 파일 서버 어댑터 |
|
|
| `httpclient/` | HTTP 클라이언트 플랫폼 |
|
|
| `jpa/` | JPA·PostgreSQL 영속성 |
|
|
| `messaging/` | 메시징 어댑터 |
|
|
| `mongodb/` | MongoDB 문서 영속성 (`advanced/`, `runbooks/` 포함) |
|
|
| `notification/` | 알림 전달 플랫폼 (`adr/` 포함) |
|
|
| `redis/` | Redis 캐시·세션 |
|
|
|
|
## 횡단 문서
|
|
|
|
| 디렉터리 | 대상 |
|
|
| --- | --- |
|
|
| `adr/` | 아키텍처 결정 기록 |
|
|
| `architecture/` | 공개 API 표면 스냅숏 |
|
|
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 |
|
|
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` |
|
|
| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT |
|
|
| `reviews/` | 모듈 코드 리뷰 결과 |
|
|
| `runbooks/` | 장애 코드별 대응 런북 (`template.md` 기준) |
|
|
| `security/` | 공개 경로 스냅숏 |
|
|
|
|
## 설계와 기록
|
|
|
|
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
|
|
|
|
| 디렉터리 | 대상 |
|
|
| --- | --- |
|
|
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
|
|
| `history/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
|
|
| `history/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
|
|
| `history/evidence/` | 작업 단계별 증거·체크포인트 |
|
|
| `history/study/` | 학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 |
|
|
|
|
`history/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
|
|
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/` 과 `history/plans/` 에 있으므로 이 디렉터리에서
|
|
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
|
|
`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256` 은
|
|
납품 당시 바이트의 해시다.
|
|
|
|
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
|
|
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는
|
|
`module-mapping.md` 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라
|
|
결과를 계획처럼 보이게 만든 글이 되기 때문이다.
|
|
|
|
## 문서 수명과 언어
|
|
|
|
규칙의 정본은 design-docs `conventions/docs-system.md`다. 이 절은 이 repo에 적용한 내용이고,
|
|
이 템플릿을 받은 파생 서비스도 이 절을 따른다.
|
|
|
|
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
|
|
| --- | --- | --- | --- | --- |
|
|
| 살아 있음 | README, `CLAUDE.md`, `AGENTS.md`, 매뉴얼(`manual/`, `work/`), 영역 운영 문서, `registries/`, `runbooks/`, `upgrade/` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다 |
|
|
| 결정 | 결정 기록(ADR) | `adr/`, `notification/adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 |
|
|
| 기록 | 설계서, 계획서, 납품 패키지, 증거, 학습 문서, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
|
|
|
|
- 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다.
|
|
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
|
|
- 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR은 문서 검사의 예외 목록에 있다(「문서 검사」).
|
|
|
|
## 기록 문서의 머리 블록
|
|
|
|
`design/`, `history/`, `adr/`, `notification/adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다.
|
|
블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).
|
|
|
|
```text
|
|
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
|
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
|
|
|
- 상태: 구현됨
|
|
- 작성일: 2026-08-11
|
|
- 요약: 한국어 한 문장
|
|
- 현재 정본: `docs/jpa/repository-adaptation.md`
|
|
- 대체됨: `docs/design/<대체한 문서>.md`
|
|
<!-- 머리 블록 끝 -->
|
|
```
|
|
|
|
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서,
|
|
`history/evidence/`·`history/plans/evidence/` 증거, `history/packages/` 납품 패키지,
|
|
`history/study/` 학습 문서. ADR의 둘째 줄은
|
|
`> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다.
|
|
- 상태는 종류마다 고정 어휘다.
|
|
|
|
| 종류 | 상태 |
|
|
| --- | --- |
|
|
| 설계서 | 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함 |
|
|
| 결정 기록 | 제안 · 채택 · 채택(보완) · 폐기 · 대체됨 |
|
|
| 계획서 | 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함 |
|
|
| 납품 패키지 · 증거 · 학습 문서 | 보관 |
|
|
|
|
- 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.
|
|
- 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.
|
|
- 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다.
|
|
- 2026-11-07에 처음 단 상태는 문서의 원래 상태 줄을 바꾼 값이다: Accepted·Approved·확정·승인 → 채택,
|
|
Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 보완 메모가 있는 ADR → 채택(보완).
|
|
상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.
|
|
`capability-status.md` 「제거된 코드」로 지운 것이 확인된 설계서 다섯은 「폐기」다.
|
|
- 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다.
|
|
|
|
## 문서와 코드를 같은 변경에서 고친다
|
|
|
|
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법:
|
|
`grep -rn '<바꾼 이름>' docs src --include=*.md`.
|
|
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·태스크는 `capability-status.md` 「제거된 코드」나
|
|
`upgrade/`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다.
|
|
- 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는
|
|
registry(`src/config/architecture/modules.json`)를 가리킨다.
|
|
- 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이
|
|
어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서는 design-docs `conventions/docs-system.md` 6절이다.
|
|
|
|
## 문서 검사
|
|
|
|
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 넷을 본다. PR마다 workflow `docs-check`가
|
|
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
|
|
문서를 낡게 만든다.
|
|
|
|
| 검사 | 보는 것 |
|
|
| --- | --- |
|
|
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
|
|
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
|
|
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
|
|
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가 |
|
|
|
|
- 하나만 돌리기: `python3 scripts/check-docs.py --only head`.
|
|
- 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서
|
|
더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은
|
|
규칙을 바꾸는 일이라 소유자 결정이 필요하다.
|
|
- 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`.
|
|
- 마크다운 상대 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다.
|
|
|
|
## 여기에 없는 것
|
|
|
|
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
|
|
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다.
|
|
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/CLAUDE.md` 가 소유한다.
|