템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼 (src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드 (src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘, 카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다. 소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절, 05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다. gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13). 코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리 해시가 이 기준 커밋 22df3525와 같다). 지운 것: - src/platforms/grpc, grpc-advanced, optional-build(343파일) - registry의 "build": "optional-grpc" 9행 - ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs, integration-main.yml optional 성능 단계와 job grpc-optional-platform-integration, release.yml job grpc-stable-release-gate와 이미지 job의 needs 한 줄 - build-logic ca.grpc-platform-module·ca.optional-architecture-registry, MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의 optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다 - 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14: 채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄 - 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘, gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리 블록 「현재 정본」만 새 자리를 말하게 했다 - DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험, adopter API 표면 검사의 optional-build 제외 경로 남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다), src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원 (ModuleRegistry, 일반 기능). 살아 있는 문서: README, docs 지도, capability-status, work/delegate· gates·decisions(새 행 「라이브러리 repo」)·defect-patterns· review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로), manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석. 새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이 고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56. 위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다 (tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전 커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck, compose smoke, 빠른 시작). 문서 검사 셋 rc=0. BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:* 프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로 받는다(docs/upgrade/2026-11-maturity-review.md 3.8절). Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
216 lines
15 KiB
Markdown
216 lines
15 KiB
Markdown
# docs
|
|
|
|
저장소의 모든 문서는 이 폴더 아래에 있다. 이 README는 두 가지를 정한다.
|
|
|
|
- 어떤 문서가 어느 폴더에 있나: 아래 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
|
|
- 문서의 수명에 따라 무엇을 어떤 언어로 고치나: 「문서 수명과 언어」.
|
|
|
|
파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.
|
|
|
|
## 문서 지도
|
|
|
|
- 표의 첫 칸이 폴더다(`docs/` 기준 경로).
|
|
- 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
|
|
- `python3 scripts/check-docs.py`의 `map` 검사가 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(「문서 검사」).
|
|
|
|
### 매뉴얼
|
|
|
|
일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.
|
|
|
|
| 폴더 | 무엇 |
|
|
| --- | --- |
|
|
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `AGENTS.md` 다음에 읽는다 |
|
|
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` |
|
|
| `ledger/` | 예측·실측 장부: 작업마다 착수 예측(p30·p50·p80과 근거)과 끝 실측을 한 줄씩 쌓는다(`ledger/estimates.jsonl`, 형식은 `ledger/README.md`) |
|
|
| `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/` | 구조화 로그 필드 사전 |
|
|
|
|
### 영역 운영 문서
|
|
|
|
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). 영역마다 파일 이름 앞머리가 다르다(`ADR-JPA-`, `NOTIF-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/`에 있으므로 이 폴더에서
|
|
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
|
|
`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256`은
|
|
납품 당시 바이트의 해시다.
|
|
|
|
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
|
|
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.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에 적용한 내용이고,
|
|
이 템플릿을 받은 파생 서비스도 이 절을 따른다.
|
|
|
|
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
|
|
| --- | --- | --- | --- | --- |
|
|
| 살아 있음 | README, `CLAUDE.md`, `AGENTS.md`, 매뉴얼(`manual/`, `work/`), 영역 운영 문서, `registries/`, `runbooks/`, `upgrade/` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다 |
|
|
| 결정 | 결정 기록(ADR) | `adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 |
|
|
| 기록 | 설계서, 계획서, 납품 패키지, 증거, 학습 문서, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
|
|
|
|
- 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다.
|
|
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
|
|
- 살아 있는 문서와 ADR 본문은 2026-11-07에 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(「문서 검사」).
|
|
- ADR 본문의 번역은 뜻을 바꾸지 않은 옮김이다. 옮기기 전 원문은 커밋 `03a313ed`에 있다(알림 ADR은 그때 다른
|
|
폴더에 있었다. 옛 경로는 `docs/upgrade/2026-11-docs-records.md`).
|
|
|
|
## 기록 문서의 머리 블록
|
|
|
|
`design/`, `history/`, `adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다.
|
|
블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다). ADR만은 본문을 한국어로 옮겼다(「문서 수명과 언어」).
|
|
|
|
```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/`)는 아직 머리 블록을 요구하지 않는다.
|
|
|
|
## 모듈 README
|
|
|
|
leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것(정본은 design-docs `conventions/docs-system.md` 6.2절):
|
|
|
|
1. 책임 한 문장과 소유하지 않는 것
|
|
2. 공개 표면(포트·API·설정 prefix)
|
|
3. 조립: 더할 한 줄, 끄는 키, 필요한 env 키
|
|
4. 테스트: registry의 Gradle 경로로 만든 명령(숫자·버전을 복사하지 않는다)
|
|
5. 더 읽을 곳: 그 폴더의 `AGENTS.md`(지역 규칙), 영역 운영 문서
|
|
|
|
## 문서와 코드를 같은 변경에서 고친다
|
|
|
|
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법:
|
|
`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.1절이고,
|
|
`readme` 검사가 그 목록(`scripts/check-docs.py`의 `README_SECTIONS`)을 본다.
|
|
|
|
## 문서 검사
|
|
|
|
`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 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
|
|
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
|
|
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
|
|
| `link` | 살아 있는 문서의 마크다운 상대 링크가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 |
|
|
| `style` | 살아 있는 문서의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안의 인용은 보지 않는다 |
|
|
|
|
- 하나만 돌리기: `python3 scripts/check-docs.py --only head`.
|
|
- 소스 세트의 resources 폴더 아래 `.md`(`src/**/src/<세트>/resources/`)는 테스트가 읽는 입력이라 문서로 보지 않는다.
|
|
- 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서
|
|
더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은
|
|
규칙을 바꾸는 일이라 소유자 결정이 필요하다.
|
|
- 줄을 지우면 같은 변경에서 `scripts/check-docs.py`의 `FROZEN`에서 그 줄의 지문도 뺀다. 남겨 두면 실패한다(남은
|
|
지문은 지운 줄을 다시 더하는 길이다). 2026-11-07 번역 단계에서 목록과 `FROZEN`이 모두 비었다.
|
|
- 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`.
|
|
- 상대 링크는 `link` 검사가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL은 lychee(`link-check` workflow)가 본다.
|
|
기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다.
|
|
|
|
## 여기에 없는 것
|
|
|
|
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
|
|
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다.
|
|
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다.
|