From d8afffce9e960b1706637aa0d8e8d5ef4d2bc3c2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:19 +0900 Subject: [PATCH] =?UTF-8?q?docs(docs):=20docs/README=EB=A5=BC=20=EB=AA=A8?= =?UTF-8?q?=EB=93=A0=20=EB=AC=B8=EC=84=9C=20=ED=8F=B4=EB=8D=94=EB=A5=BC=20?= =?UTF-8?q?=EB=8D=AE=EB=8A=94=20=EC=A7=80=EB=8F=84=EB=A1=9C=20=EB=8B=A4?= =?UTF-8?q?=EC=8B=9C=20=EC=93=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `docs/README.md`의 폴더 표에 `ci-cd/`, `compatibility/`, `mongo/`, `objectstorage/`, `observability/`, `roadmap/`, `testing/`, `upgrade/`, `web/`, `websocket/`가 없다. 폴더 밖 문서 둘(`capability-status.md`, `storage-capability-boundary.md`)도 없다. 처음 온 사람이 문서를 찾을 수 없다. 고른 방법: 「문서 지도」 절 하나에 목적별 표(매뉴얼, 계약과 스냅숏, 영역 운영 문서, 운영과 전달, 결정 기록, 설계와 기록, 폴더 밖 문서)를 두고, 표의 첫 칸에 `폴더/`를 적는다. 다음 커밋의 `map` 검사가 이 첫 칸을 읽는다. 「문서 검사」 절에 `map`·`readme` 검사, resources 폴더 제외, `.lycheeignore` 규칙을 적는다. 위험·한계: 알림 ADR은 지금 위치 `notification/adr/`로 적었다. 옮기는 변경이 지도도 고친다. 검증: `python3 scripts/check-docs.py` rc=0, `python3 scripts/check-work-docs.py --links docs/README.md` 깨진 링크 0. --- docs/README.md | 123 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 88 insertions(+), 35 deletions(-) diff --git a/docs/README.md b/docs/README.md index 54351e62..e43e5876 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,60 +1,108 @@ # docs -저장소의 모든 문서는 이 디렉터리 아래에 있다. 규칙은 둘이다: 어떤 문서를 어디에 두는지(아래 표), -문서의 수명에 따라 무엇을 어떤 언어로 고치는지(「문서 수명과 언어」). 파일 목록은 디렉터리를 직접 읽는다. -개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다. +저장소의 모든 문서는 이 폴더 아래에 있다. 이 README는 두 가지를 정한다. -## 어댑터별 운영 문서 +- 어떤 문서가 어느 폴더에 있나: 아래 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다. +- 문서의 수명에 따라 무엇을 어떤 언어로 고치나: 「문서 수명과 언어」. -각 어댑터의 지원 범위, 설정, 보안, 운영, 마이그레이션 문서다. 코드와 함께 갱신되어야 하는 문서이고, -`docs/httpclient/` 는 `scripts/verify-httpclient-docs.py` 가 코드에서 뽑은 이름과 대조한다. +파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다. -| 디렉터리 | 대상 | +## 문서 지도 + +- 표의 첫 칸이 폴더다(`docs/` 기준 경로). +- 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다. +- `python3 scripts/check-docs.py`의 `map` 검사가 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(「문서 검사」). + +### 매뉴얼 + +일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다. + +| 폴더 | 무엇 | | --- | --- | -| `fileserver/` | 파일 서버 어댑터 | -| `httpclient/` | HTTP 클라이언트 플랫폼 | -| `jpa/` | JPA·PostgreSQL 영속성 | -| `messaging/` | 메시징 어댑터 | -| `mongodb/` | MongoDB 문서 영속성 (`advanced/`, `runbooks/` 포함) | -| `notification/` | 알림 전달 플랫폼 (`adr/` 포함) | -| `redis/` | Redis 캐시·세션 | - -## 횡단 문서 - -| 디렉터리 | 대상 | -| --- | --- | -| `adr/` | 아키텍처 결정 기록 | -| `architecture/` | 공개 API 표면 스냅숏 | -| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 | +| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 | | `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` | -| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT | -| `reviews/` | 모듈 코드 리뷰 결과 | -| `runbooks/` | 장애 코드별 대응 런북 (`template.md` 기준) | -| `security/` | 공개 경로 스냅숏 | +| `testing/` | 테스트 전략: 테스트 종류 다섯, source set, 어떤 테스트를 어디에 두나, Gradle 실행 계층 | -## 설계와 기록 +### 계약과 스냅숏 + +코드와 테스트가 대조하는 정본이다. 바꾸면 공개 계약이 바뀔 수 있다(`work/README.md` 2절). + +| 폴더 | 무엇 | +| --- | --- | +| `registries/` | 레지스트리: env 키, 오류 코드, 메트릭, HTTP 헤더, 로그(MDC) 키, 비밀 분류, use case capability, 객체 저장소 준비도. 테스트가 코드와 대조한다 | +| `web/` | HTTP wire 계약(`web/http-contract.md`), PATCH·스트리밍 계약, 선택형 web 기능(`web-advanced`), web 장애 대응 | +| `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 | +| `security/` | 기본 공개 경로 스냅숏. `verifyPublicPathSnapshot`이 대조한다 | +| `observability/` | 구조화 로그 필드 사전 | +| `compatibility/` | gRPC 플랫폼 지원 매트릭스(무엇에 대해 인증했고 무엇은 지켜보기만 하나) | + +### 영역 운영 문서 + +capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마이그레이션이다. 코드와 같은 변경에서 고친다. +`httpclient/`는 `scripts/verify-httpclient-docs.py`가 코드에서 뽑은 이름과 대조한다. + +| 폴더 | 무엇 | +| --- | --- | +| `fileserver/` | 파일 서버 | +| `httpclient/` | 외부 HTTP 호출(HTTP client 플랫폼) | +| `jpa/` | JPA·PostgreSQL 영속성 | +| `messaging/` | 메시징 adapter | +| `mongodb/` | MongoDB 문서 영속성 | +| `mongodb/advanced/` | MongoDB 고급 기능(암호화, 멀티 테넌시, 샤딩). 설정 키가 아니라 라이브러리 API로 켠다 | +| `mongodb/runbooks/` | MongoDB 장애 대응 | +| `mongo/` | MongoDB 영속성 설정 예시 파일(Spring이 읽지 않는 예시) | +| `notification/` | 알림 전달 플랫폼 | +| `objectstorage/` | 객체 저장소의 설정 필드와 env 이름 표(`env-fields.yaml`) | +| `redis/` | Redis 캐시·세션 | +| `websocket/` | WebSocket handler 장애 대응 | + +### 운영과 전달 + +| 폴더 | 무엇 | +| --- | --- | +| `runbooks/` | 오류 코드별 장애 대응 런북(`runbooks/template.md` 형식) | +| `ci-cd/` | CI/CD 경계: 검증·빌드(CI)와 배포(CD)의 경계, 템플릿과 파생 서비스가 각각 돌릴 검증 | +| `upgrade/` | 파생 서비스용 변경 안내: 템플릿 변경을 받을 때 서비스가 할 일 | +| `roadmap/` | 아직 구현하지 않은 다음 단계와 그 조건 | + +### 결정 기록 + +| 폴더 | 무엇 | +| --- | --- | +| `adr/` | 아키텍처 결정 기록(ADR) | +| `notification/adr/` | 알림 플랫폼의 결정 기록 | + +### 설계와 기록 설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다. -| 디렉터리 | 대상 | +| 폴더 | 무엇 | | --- | --- | | `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md` | | `history/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` | | `history/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 | | `history/evidence/` | 작업 단계별 증거·체크포인트 | | `history/study/` | 학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 | +| `reviews/` | 코드 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나 | -`history/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을 -남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/` 과 `history/plans/` 에 있으므로 이 디렉터리에서 +`history/packages/<어댑터>/`는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을 +남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/`과 `history/plans/`에 있으므로 이 폴더에서 문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다. -`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256` 은 +`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256`은 납품 당시 바이트의 해시다. 계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로 조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는 -`module-mapping.md` 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라 +`module-mapping.md`가 기록한다. 계획서를 나중에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다. +### 폴더 밖 문서 + +| 문서 | 무엇 | +| --- | --- | +| [capability-status.md](capability-status.md) | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) | +| [storage-capability-boundary.md](storage-capability-boundary.md) | 파일 서버와 객체 저장소가 각각 맡는 경계 | + ## 문서 수명과 언어 규칙의 정본은 design-docs `conventions/docs-system.md`다. 이 절은 이 repo에 적용한 내용이고, @@ -118,11 +166,12 @@ - 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는 registry(`src/config/architecture/modules.json`)를 가리킨다. - 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이 - 어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서는 design-docs `conventions/docs-system.md` 6절이다. + 어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고, + `readme` 검사가 그 목록(`scripts/check-docs.py`의 `README_SECTIONS`)을 본다. ## 문서 검사 -`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 넷을 본다. PR마다 workflow `docs-check`가 +`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여섯을 본다. PR마다 workflow `docs-check`가 돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이 문서를 낡게 만든다. @@ -132,13 +181,17 @@ | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | | `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가 | +| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | +| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | - 하나만 돌리기: `python3 scripts/check-docs.py --only head`. +- 소스 세트의 resources 폴더 아래 `.md`(`src/**/src/<세트>/resources/`)는 테스트가 읽는 입력이라 문서로 보지 않는다. - 예외 목록 `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`가 본다. +- 마크다운 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다. + 기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다. ## 여기에 없는 것