Files
clean-architecture-backend-…/docs/README.md
T
DongHyeonka 3c73fc333c docs(agents)!: 루트 AGENTS.md를 40줄 정본으로 줄이고 CLAUDE.md가 가져온다
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은
AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만
닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은
규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은
AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs
harness/01-harness-design.md 13절 Q1·Q2·Q3).

- AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증,
  일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄.
- 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새),
  테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스),
  계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새
  src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 →
  src/composition/AGENTS.md(새), capability 규칙·완료 기준 →
  docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 →
  .claude/rules/settings-and-runtime.md, 문서 편집 규칙 →
  .claude/rules/docs.md, 템플릿 재사용 체크리스트 → README
  「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길·
  작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다.
- 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛
  행에 취소선을 긋고 「지침 배치」 행을 더했다.
- check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10),
  진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지,
  .claude/rules·skills·agents 문서의 이력 ID와 링크를 본다.
- DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서
  읽는다. 단언은 그대로다.

버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함),
CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크.

위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로
읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다.

검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10),
check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트
변경은 마지막 트리에서 desktop documentContractTest로 확인한다.

BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로
옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행.
2026-11-07 21:59:42 +09:00

14 KiB

docs

저장소의 모든 문서는 이 폴더 아래에 있다. 이 README는 두 가지를 정한다.

  • 어떤 문서가 어느 폴더에 있나: 아래 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
  • 문서의 수명에 따라 무엇을 어떤 언어로 고치나: 「문서 수명과 언어」.

파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.

문서 지도

  • 표의 첫 칸이 폴더다(docs/ 기준 경로).
  • 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
  • python3 scripts/check-docs.py의 map 검사가 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(「문서 검사」).

매뉴얼

일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.

폴더 무엇
work/ 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 AGENTS.md 다음에 읽는다
manual/ 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(scripts/new-feature.sh). 입구는 work/new-feature.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/ 구조화 로그 필드 사전
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). 영역마다 파일 이름 앞머리가 다르다(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마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」)
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만은 본문을 한국어로 옮겼다(「문서 수명과 언어」).

<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 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.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가 첫 줄 제목, 그 아래 한 문단, 정해진 ## 절을 정해진 순서로 가지는가
  • 하나만 돌리기: 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.
  • 마크다운 링크는 이 검사가 아니라 lychee(link-check workflow)와 scripts/check-work-docs.py --links가 본다. 기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 .lycheeignore에 더한다.

여기에 없는 것

  • 실행되는 검증 스크립트는 문서가 아니다. scripts/ 와 .github/scripts/ 에 있다.
  • 모듈 레지스트리·Gradle 정책은 src/config/architecture/modules.json 과 src/build.gradle 이 소유한다.
  • 각 모듈의 지역 규칙은 해당 모듈의 src/**/AGENTS.md 가 소유한다.