feat(harness)!: 백엔드에 Claude Code 하네스를 적용하고 매뉴얼 빈틈을 채운다 #5
@@ -0,0 +1,28 @@
|
||||
---
|
||||
name: arch-reviewer
|
||||
description: 바뀐 Java·Gradle·registry가 이 repo의 계층 규칙(HARD-STOP 1~5, registry allowed_dependencies, leaf 지역 규칙)을 지키는지 읽기만 하고 판정을 돌려준다. 구현이나 수정 묶음을 끝내고 커밋이나 PR 전에, 또는 사용자가 "구조 리뷰", "경계 확인", "레이어 위반 없나"라고 할 때 쓴다. 파일을 고치지 않는다.
|
||||
tools: Read, Grep, Glob, Bash
|
||||
model: inherit
|
||||
---
|
||||
|
||||
# arch-reviewer — 계층 규칙 리뷰(읽기 전용)
|
||||
|
||||
맡긴 쪽이 준 범위(기준 커밋, diff, 경로)만 본다. 결과만 돌려주고 파일을 쓰거나 고치지 않는다. Bash는 `git diff`, `git log`, `git grep`, `python3 scripts/check-*.py` 같은 읽기 명령에만 쓴다. Gradle·Docker는 돌리지 않는다(노트북에서 막히고, 게이트는 맡긴 쪽이 desktop에서 돌린다).
|
||||
|
||||
## 순서
|
||||
|
||||
1. 루트 `AGENTS.md`의 HARD-STOP과 지도를 읽는다.
|
||||
2. 바뀐 파일마다 registry `src/config/architecture/modules.json`의 `source_path`로 leaf를 찾고, 가장 가까운 `AGENTS.md`(leaf, family)를 읽는다.
|
||||
3. 운영 소스의 import를 본다: 순수성(`domain-core`·`application-*`·`shared-contract`의 framework import), inbound의 repository·Spring Data·entity 사용, inbound DTO가 core로 들어가는지, `dev.caskeleton.*` 주인 leaf가 `allowed_dependencies`(전이 포함)에 있는지.
|
||||
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 가지 않았는지 본다(HARD-STOP 4). 이것은 import로 안 보이니 코드를 읽는다.
|
||||
5. `build.gradle`·registry를 바꿨으면 새 edge가 registry에 있고 방향 그림(`app-bootstrap → adapter → application-core → domain-core`)을 거스르지 않는지 본다.
|
||||
|
||||
## 돌려줄 것
|
||||
|
||||
```text
|
||||
판정: 통과 / 위반 있음 / 판단 못 함
|
||||
발견: (위반마다) HARD-STOP 번호 · 파일:줄 · 무엇이 무엇을 쓰나 · 근거 규칙(문서 경로)
|
||||
확인 못 한 것: (읽지 못한 파일, 게이트로만 판정할 것 — 예: architectureCheck)
|
||||
```
|
||||
|
||||
발견이 없으면 "발견 0"과 본 파일 수를 적는다. 추측은 발견에 넣지 않고 「확인 못 한 것」에 넣는다.
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
name: code-simplifier
|
||||
description: 지정한 파일·diff에서 동작을 바꾸지 않고 줄일 수 있는 곳(중복, 죽은 코드, 불필요한 분기·래퍼, 더 단순한 표준 API)을 찾아 제안만 돌려준다. 구현을 마친 뒤 "단순하게", "정리할 곳", "중복 없나"라고 할 때나 리뷰 전에 쓴다. 파일을 고치지 않는다. 고치는 일은 맡긴 세션이 한다.
|
||||
tools: Read, Grep, Glob
|
||||
model: inherit
|
||||
---
|
||||
|
||||
# code-simplifier — 단순화 제안(읽기 전용)
|
||||
|
||||
맡긴 범위만 본다. 제안만 돌려주고 파일을 쓰지 않는다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- 동작을 바꾸는 제안을 하지 않는다. 공개 계약(HTTP wire, 오류 코드, env 키, API surface)을 바꾸는 제안은 하지 않는다.
|
||||
- 계층 규칙(루트 `AGENTS.md` HARD-STOP, 가장 가까운 `AGENTS.md`)을 어기게 만드는 제안을 하지 않는다. 예: 포트를 지우고 adapter를 직접 부르게 하기.
|
||||
- 테스트를 줄이는 제안은 단언이 약해지지 않을 때만 한다(`.claude/rules/java-tests.md`).
|
||||
- 요청 범위 밖의 큰 리팩터링은 제안하지 않고 「범위 밖에서 본 것」에 한 줄로 적는다.
|
||||
|
||||
## 돌려줄 것
|
||||
|
||||
```text
|
||||
제안: (하나마다) 파일:줄 · 지금 모양 · 바꿀 모양(짧은 코드) · 왜 동작이 같은가 · 그것을 보일 테스트
|
||||
범위 밖에서 본 것: (있으면)
|
||||
```
|
||||
|
||||
제안이 없으면 "제안 0"과 본 파일 수를 적는다.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
name: verify-api
|
||||
description: 지정한 브랜치나 커밋의 앱을 desktop에서 실제로 띄워 health와 지정한 HTTP endpoint를 호출하고, 응답 코드·본문 요약·로그 경로만 돌려준다. 동작을 바꾼 변경을 끝내고 "직접 돌려 봐", "앱이 뜨나", "API 확인"이라고 할 때나 PR 전 확인으로 쓴다. 노트북에서 Gradle·Docker를 돌리지 않고, 노트북 checkout의 파일을 고치지 않는다.
|
||||
tools: Bash, Read, Grep, Glob
|
||||
model: inherit
|
||||
---
|
||||
|
||||
# verify-api — desktop에서 앱을 띄워 확인
|
||||
|
||||
Gradle·Docker는 desktop에서만 돈다. 절차의 정본은 `docs/work/operate.md` 4.1절(실행 위치)이고, 이 문서는 그 안에서 앱을 띄우는 순서만 적는다. 노트북 checkout은 읽기만 한다.
|
||||
|
||||
## 받을 것
|
||||
|
||||
- 확인할 브랜치(push된 것) 또는 기준 커밋 + 패치(4.1절 「push 전에 검증하기」), 작업 이름.
|
||||
- 부를 endpoint 목록과 기대 응답. 없으면 `GET /api/healthcheck`만 본다.
|
||||
|
||||
## 순서
|
||||
|
||||
1. desktop에 따로 worktree를 만든다. 기존 checkout `~/workspace/clean-architecture-backend-template`의 브랜치와 `stash@{0}`는 건드리지 않는다.
|
||||
2. 로그 폴더 `~/<작업 이름>-logs/`를 만들고 `uptime`으로 부하를 본다.
|
||||
3. worktree 루트에서 `flock /tmp/claude-gates/heavy.lock scripts/bootstrap-local.sh > ~/<작업 이름>-logs/bootstrap.log 2>&1; echo "rc=$?"`를 돌린다. 스크립트가 컴파일 → DB 기동 → 앱 기동 → health 200과 `status=UP`을 차례로 본다.
|
||||
4. 앱이 떠 있는 동안 받은 endpoint를 `curl --silent --show-error --max-time 5 --write-out '\n%{http_code}'`로 부르고 응답을 로그 폴더에 남긴다.
|
||||
5. 저장소 루트에서 `docker compose --profile '*' down`으로 내린다. 컨테이너가 만든 root 소유 폴더가 남으면 4.1절의 정리법을 따른 뒤 worktree를 지운다.
|
||||
|
||||
## 돌려줄 것
|
||||
|
||||
```text
|
||||
결과: 떴다 / 안 떴다(멈춘 bootstrap 단계)
|
||||
호출: (endpoint마다) 메서드 경로 · HTTP 코드 · 기대와 같은가 · 본문 요약 한 줄
|
||||
증거: desktop 로그 경로, 트리 해시(git rev-parse HEAD^{tree})
|
||||
남은 것: 지우지 못한 worktree·컨테이너, 확인 못 한 endpoint
|
||||
```
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
paths:
|
||||
- "**/*.md"
|
||||
---
|
||||
|
||||
# 문서를 고칠 때
|
||||
|
||||
- 문서 위치·언어·머리 블록 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다.
|
||||
- 기록 문서(`docs/design/`, `docs/history/`, `docs/reviews/`, `docs/adr/`)는 맨 위 머리 블록만 고친다.
|
||||
- 진입 문서(`AGENTS.md`, 모든 `src/**/AGENTS.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다.
|
||||
- 문서를 읽는 테스트가 있다. 태그 `document-contract`(main 단계)·`repository-contract`(PR)다. 고친 문서의 경로로 `git grep -n '<경로>' -- 'src/*.java'`를 해서 그 테스트를 찾고 desktop에서 돌린다.
|
||||
- 고친 뒤 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`를 돌린다. 편집 훅이 실패 줄을 먼저 알려 준다.
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
paths:
|
||||
- "src/**/src/test/**/*.java"
|
||||
- "src/**/src/testFixtures/**/*.java"
|
||||
- "src/**/src/*Test/**/*.java"
|
||||
- "src/**/src/*Testkit/**/*.java"
|
||||
---
|
||||
|
||||
# Java 테스트 작성 규칙
|
||||
|
||||
새로 쓰거나 고치는 테스트에 적용한다. 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`, 계층별로 무엇을 검증하는지는 그 계층의 `AGENTS.md` 「테스트」 절이다.
|
||||
|
||||
## 작성 규칙
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로 쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트 메서드를 고칠 때 한국어로 바꾼다. 같은 클래스의 고치지 않은 메서드는 바꾸지 않아도 되고, 바꾸면 같은 커밋에 넣고 보고에 적는다.
|
||||
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할 것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다. 예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때 `// when & then`까지 허용). 한 줄 테스트와 ArchUnit `.check()`는 주석 없이 쓴다.
|
||||
4. `@Nested`는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다.
|
||||
5. then은 when의 결과 하나만 단언한다. 여러 필드는 `usingRecursiveComparison()` 또는 `extracting(..).containsExactly(..)`로 한 번에 비교한다. `isNotNull`·`isPresent`·`doesNotThrowAnyException`만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외). 예외는 타입과 reason·message를 함께 단언한다. 표 형태 입력은 `@ParameterizedTest`로 쓴다.
|
||||
6. 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는 포트는 fake와 adapter가 같은 추상 계약 테스트(`XxxContract`)를 통과한다. Mockito는 프레임워크 경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다.
|
||||
|
||||
GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고, 실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다.
|
||||
|
||||
## 코드만 보고는 헷갈리는 것
|
||||
|
||||
- 저장소 파일을 읽는 테스트는 태그가 있어야 한다. 문서와 대조하면 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow·Compose를 읽으면 `repository-contract`(PR)다. 태그 없이 저장소를 읽으면 `test`에서 실패한다. 이유는 `src/build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」다.
|
||||
- 성능 lane에는 단언을 끄는 스위치가 없다. `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 하나라도 있으면 테스트 전에 실패한다.
|
||||
- 테스트는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절).
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
paths:
|
||||
- "src/**/*Settings.java"
|
||||
- "src/**/settings/**"
|
||||
- "src/**/autoconfigure/**"
|
||||
- "src/**/application*.yml"
|
||||
- "src/**/application*.yaml"
|
||||
- "src/**/config/module-defaults/**"
|
||||
- "src/.env.example"
|
||||
- "src/.env.local.example"
|
||||
- "src/Dockerfile"
|
||||
- "compose.yaml"
|
||||
- "compose/**"
|
||||
- "src/**/compose/**"
|
||||
- "src/app-bootstrap/compose-lanes/**"
|
||||
---
|
||||
|
||||
# 설정과 런타임 규칙
|
||||
|
||||
## 설정
|
||||
|
||||
- 비밀 값(토큰, 비밀번호, 개인 키)을 코드, 테스트 fixture, 문서 예시에 하드코딩하지 않는다. 예시 값이면 `example`·`dummy`·`changeme`처럼 예시임이 보이게 쓴다.
|
||||
- 새 설정 그룹은 typed settings class로 만든다. 흩어진 `@Value`보다 configuration properties와 settings class를 쓴다.
|
||||
- 새 settings class를 만들면 바인딩·값 검증 테스트를 더한다.
|
||||
- capability 모듈의 설정 prefix는 하나다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor다(`docs/manual/10-capabilities.md` 기준 4, Redis 예외 포함).
|
||||
- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다(권한 설정이 막는다). 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다.
|
||||
- `application.yml`은 환경마다 안전한 기본값과 분명한 자리표시자만 담는다.
|
||||
|
||||
## Docker·Compose
|
||||
|
||||
- `src/Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다.
|
||||
- container 안에서 필요한 profile, port, env 키를 문서나 예시 설정에 반영한다.
|
||||
- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다(「개발 환경」과 lane overlay의 차이는 `docs/work/reference/terms.md`). 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`).
|
||||
- Docker는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절).
|
||||
+37
-1
@@ -1,7 +1,43 @@
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Agent"
|
||||
"Read(**/.env)",
|
||||
"Read(**/.env.local)",
|
||||
"Read(**/.env.lane)",
|
||||
"Edit(**/.env)",
|
||||
"Edit(**/.env.local)",
|
||||
"Edit(**/.env.lane)"
|
||||
]
|
||||
},
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write|MultiEdit",
|
||||
"hooks": [
|
||||
{"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py pre-edit", "timeout": 10}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write|MultiEdit",
|
||||
"hooks": [
|
||||
{"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py post-edit", "timeout": 60}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"hooks": [
|
||||
{"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py post-bash", "timeout": 10}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"hooks": [
|
||||
{"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py stop", "timeout": 10}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
name: desktop-gates
|
||||
description: 이 repo에서 Gradle·Docker·테스트·게이트·성능 측정을 돌려야 할 때 쓴다. 노트북에서는 돌리지 않고 desktop에서 공유 잠금 아래 돌린다. 사용자가 "테스트 돌려", "게이트", "검증해", "check 돌려", "PR 단계 돌려"라고 하거나, 편집 훅이 턴 끝에 desktop 검증이 없다고 알렸거나, 노트북의 gradlew·docker 실행이 훅에 막혔을 때 부른다. 커밋 전 트리를 패치로 보내 같은 트리에서 돌리는 법, 로그·rc 남기기, 정리까지 준다.
|
||||
---
|
||||
|
||||
# desktop에서 게이트 돌리기
|
||||
|
||||
정본은 `docs/work/operate.md` 4.1절(실행 위치)·4.2절(기록)과 `docs/work/reference/gates.md`(무엇을 돌릴지)다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. CI 재편에서 검증 진입점 스크립트(설계 이름 `verify.sh`)가 생기면 이 절차를 그 스크립트가 대신한다.
|
||||
|
||||
1. 돌릴 게이트를 고른다: 바꾼 것에 맞는 게이트는 `gates.md` 2절, PR·main 단계 묶음은 3절이다. leaf의 Gradle path는 registry `gradle_path`에서 읽는다.
|
||||
2. 트리를 정한다. push가 허용됐으면 push한 브랜치, 아니면 4.1절 「push 전에 검증하기」대로 기준 커밋 + 패치를 보내고 노트북 `git write-tree`와 desktop `git write-tree`가 같은지 본다.
|
||||
3. desktop에 따로 worktree를 만든다. 기존 checkout의 브랜치와 `stash@{0}`는 건드리지 않는다. 로그 폴더는 `~/<작업 이름>-logs/`다.
|
||||
4. `uptime`을 적고, 게이트마다 `flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"`로 하나씩 돌린다. 증거로 쓸 실행은 `--rerun`이나 `--no-build-cache`로 캐시 결과를 쓰지 않는다(`gates.md` 4절).
|
||||
5. 테스트 수는 결과 XML 사본에서 센다(`gates.md` 4절). 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다(`operate.md` 7절).
|
||||
6. 다른 세션이 잠금을 쥐고 있으면 기다린다. 기다리는 동안 다른 일을 하고, 잠금 대기는 완료나 첫 실패에서 끝나는 대기 하나로 둔다.
|
||||
7. 끝나면 compose를 내리고(`docker compose … down`) worktree를 지운다. root 소유 폴더가 남으면 4.1절의 정리법을 쓴다.
|
||||
8. 보고에는 게이트, rc, 직전 부하, 로그 경로, 대상 트리 해시, 캐시 여부를 적는다.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
name: new-feature
|
||||
description: 이 백엔드 템플릿에 새 업무 기능(도메인 개념, 유스케이스, endpoint)이나 새 capability 모듈을 더할 때 쓴다. 사용자가 "기능 추가", "새 API", "새 유스케이스", "새 도메인", "capability 모듈 만들기", "/new-feature <이름>"이라고 하거나, brief의 작업 종류가 docs/work/new-feature.md일 때 부른다. 생성 명령 scripts/new-feature.sh부터 시작해 안쪽 계층부터 채우고 desktop에서 검증하는 순서를 준다. 있는 기능을 고치는 일은 이 스킬이 아니라 docs/work/improve.md다.
|
||||
---
|
||||
|
||||
# 새 기능 만들기
|
||||
|
||||
정본은 `docs/work/new-feature.md`(크기·완료 기준·하지 말 것)와 `docs/manual/`(만드는 순서와 판단 지점)이다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다.
|
||||
|
||||
1. `docs/work/README.md`와 `docs/work/new-feature.md`를 끝까지 읽는다. 크기를 정한다. 새 capability 모듈, 새 leaf, 새 공개 계약(HTTP 경로·오류 코드·env 키)은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다.
|
||||
2. 받을 것을 확인한다: 기능 이름(PascalCase), 저장소 선택(어떤 persistence leaf, migration 번호대), 권한, 재전송될 수 있는 쓰기인지. 저장소 선택은 사람이 정한다. brief에 없으면 묻는다.
|
||||
3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다.
|
||||
4. 뼈대: 노트북에서는 `scripts/new-feature.sh <FeatureName> --no-format`. 포맷은 편집 훅이 파일마다 맞추고, 마지막에 desktop `./gradlew spotlessApply`로 한 번 더 본다.
|
||||
5. 안쪽부터 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립(`docs/manual/02-new-feature.md`). 필요한 장만 더 읽는다: 저장 04, 재시도될 쓰기 05, 오류 06, 권한 07, 테스트 08, 이벤트 09, capability 10.
|
||||
6. 동작은 테스트를 먼저 쓴다(`.claude/rules/java-tests.md`). 포트마다 fake 하나와 공유 계약(`XxxContract`)을 포트 소유 leaf의 testFixtures에 두고, 실제 adapter도 실 DB lane에서 같은 계약을 상속한다.
|
||||
7. 편집 훅의 레이어 의존 알림(N1)이 나오면 그 자리에서 고친다. 의도한 edge면 registry가 먼저다.
|
||||
8. 건드린 leaf마다 `<gradle-path>:check`, 경계를 넘었으면 `architectureCheck`, 바뀐 표면의 검사(공개 경로·env 키·의존성 잠금)를 desktop에서 돌린다(스킬 `desktop-gates`). 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(구조 리뷰)와 `verify-api`(앱을 띄워 호출)에 맡긴다.
|
||||
9. `docs/manual/11-checklist.md`를 한 줄씩 확인하고, `docs/work/new-feature.md` 8절 형식으로 보고한다.
|
||||
@@ -7,6 +7,7 @@
|
||||
*.yml text eol=lf
|
||||
*.yaml text eol=lf
|
||||
*.json text eol=lf
|
||||
*.jsonl text eol=lf
|
||||
*.md text eol=lf
|
||||
gradlew text eol=lf
|
||||
gradlew.bat text eol=crlf
|
||||
@@ -20,3 +21,6 @@ gradlew.bat text eol=crlf
|
||||
*.jar binary
|
||||
*.zip binary
|
||||
*.gz binary
|
||||
|
||||
# Ledger lines are only appended; a union merge keeps both branches' new lines (docs/ledger/README.md).
|
||||
docs/ledger/estimates.jsonl merge=union
|
||||
|
||||
+4
-1
@@ -1,9 +1,12 @@
|
||||
.vscode/
|
||||
src/**/bin/
|
||||
# Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project
|
||||
# settings file is committed: it denies the Agent tool for everyone (AGENTS.md 「Superpowers Workflow」).
|
||||
# settings, path rules, skills and subagent definitions are committed: everyone who opens the repository gets them (CLAUDE.md).
|
||||
.claude/*
|
||||
!.claude/settings.json
|
||||
!.claude/rules/
|
||||
!.claude/agents/
|
||||
!.claude/skills/
|
||||
|
||||
# Operator input, not a build input. The examples beside it are the tracked contract;
|
||||
# verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one.
|
||||
|
||||
@@ -1,344 +1,37 @@
|
||||
# AGENTS.md
|
||||
# AGENTS.md — 백엔드 템플릿의 정본
|
||||
|
||||
## 프로젝트 정체성
|
||||
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다.
|
||||
|
||||
이 저장소는 단순한 예제 블로그 애플리케이션이 아니라, Java 21 + 버전 카탈로그에 고정된 Spring Boot 4.x + Gradle 멀티모듈 기반의 Clean Architecture 템플릿이다.
|
||||
## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다
|
||||
|
||||
기본 패키지는 `dev.caskeleton`이다. 업무 기능의 예시는 `scripts/new-feature.sh`의 출력과 `docs/manual/`이다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
|
||||
1. `domain-core`가 framework·transport·database·cloud 의존성을 가진다.
|
||||
2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
|
||||
3. inbound DTO가 `application-core`나 `domain-core`로 들어간다.
|
||||
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
|
||||
5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
|
||||
6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
|
||||
7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
|
||||
|
||||
## Prime Directive
|
||||
## 지도
|
||||
|
||||
에이전트는 속도보다 아키텍처 보존을 우선한다.
|
||||
- Gradle 루트는 `src/`다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registry `src/config/architecture/modules.json`이다. 문서는 leaf 개수를 적지 않는다.
|
||||
- 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다.
|
||||
- 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `src/build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다.
|
||||
- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). `src/platforms/*`는 계층이 아닌 들여온 제품, `src/composition/*`는 조립만 한다.
|
||||
- capability는 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`.
|
||||
|
||||
동작하는 코드라도 HARD-STOP 조건을 하나라도 위반하면 완료된 작업이 아니다.
|
||||
## 맡은 일
|
||||
|
||||
다음 HARD-STOP 7개 항목이 이 저장소의 정본(canonical) 로컬 정책 권위이자 SSOT다.
|
||||
먼저 `docs/work/README.md`, 그다음 맡은 일의 playbook 하나를 끝까지 읽는다(모두 `docs/work/`): 새 기능 `new-feature.md` · 리뷰·수정·리팩터링 `improve.md` · 대안 비교와 소유자 결정 `research-design.md` · 문서 `docs-writing.md` · 게이트·릴리스·파생 서비스 `operate.md` · 일 나누기 `delegate.md`. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.
|
||||
|
||||
1. `domain-core`가 framework, transport, database, cloud 의존성을 가진다.
|
||||
2. controller가 repository, Spring Data interface, persistence entity를 직접 사용한다.
|
||||
3. inbound DTO가 `application-core` 또는 `domain-core`로 유출된다.
|
||||
4. 비즈니스 규칙이 mapper, filter, configuration, settings, controller로 이동한다.
|
||||
5. 프로젝트 의존성이 `src/config/architecture/modules.json` 또는 Gradle 의존성 검증을 위반한다.
|
||||
6. 관련 검증 없이, 또는 실행하지 못한 이유를 밝히지 않고 완료를 주장한다.
|
||||
7. 결론의 범위와 위험에 맞는 증거 없이 repository/corpus 전체 결론을 내린다.
|
||||
## 검증
|
||||
|
||||
root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 한 줄씩 가리킨다. 두 문서가 어긋나면
|
||||
이 `AGENTS.md` 목록이 우선한다. 일의 종류별 절차는 `docs/work/`에 있다. 자동 강제 범위는 아래 Gradle
|
||||
정책 권위와 ArchUnit/Test가 담당한다.
|
||||
- leaf 하나: registry의 `gradle_path`로 `./gradlew <gradle-path>:check --console=plain`(`src/`에서). 기억이나 폴더 이름으로 짐작하지 않는다.
|
||||
- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때). 게이트 고르기는 `docs/work/reference/gates.md`.
|
||||
- 문서·지침을 고쳤으면 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`.
|
||||
|
||||
## Superpowers Workflow
|
||||
## 일하는 방식
|
||||
|
||||
이 프로젝트에서 에이전트는 관련 Superpowers 스킬을 먼저 확인하고, 작업 성격에 맞는 스킬을 사용한다. 사용자 지시와 이 `AGENTS.md`가 로컬 프로젝트의 최상위 규칙이며, Superpowers는 그 규칙을 실행하기 위한 작업 방식이다.
|
||||
|
||||
사용 가능한 주요 스킬과 트리거:
|
||||
|
||||
- `superpowers:using-superpowers`: 대화나 작업을 시작할 때 관련 스킬을 확인한다.
|
||||
- `superpowers:brainstorming`: 기능 설계, 구조 변경, 동작 변경, 새 문서 정책 수립 전에 사용한다.
|
||||
- `superpowers:writing-plans`: 승인된 설계가 있고 작업이 여러 단계로 나뉠 때 사용한다.
|
||||
- `superpowers:executing-plans`: 작성된 계획을 현재 세션에서 순차 실행할 때 사용한다.
|
||||
- `superpowers:subagent-driven-development`, `superpowers:dispatching-parallel-agents`: 이 저장소에서는
|
||||
쓰지 않는다. 세션 안의 하위 에이전트(Agent 도구)는 `.claude/settings.json`이 막는다. 일을 나눠
|
||||
맡길 때는 사람이 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). 다른 스킬이
|
||||
하위 에이전트를 띄우라고 하면 그 단계는 같은 세션이 직접 한다.
|
||||
- `superpowers:test-driven-development`: 기능 추가와 버그 수정을 테스트 우선으로 진행할 때 사용한다.
|
||||
- `superpowers:systematic-debugging`: 버그, 실패한 테스트, 예상 밖 동작을 다룰 때 사용한다.
|
||||
- `superpowers:verification-before-completion`: 완료, 수정됨, 통과함을 주장하기 전에 사용한다.
|
||||
- `superpowers:requesting-code-review`: 의미 있는 구현을 마친 뒤 병합 또는 PR 전에 사용한다.
|
||||
- `superpowers:receiving-code-review`: 리뷰 피드백을 적용하기 전에 사용한다.
|
||||
- `superpowers:finishing-a-development-branch`: 구현과 검증이 끝난 브랜치를 정리할 때 사용한다.
|
||||
- `superpowers:using-git-worktrees`: 격리된 작업 공간이 필요할 때 사용한다.
|
||||
- `superpowers:writing-skills`: 스킬을 만들거나 수정할 때 사용한다.
|
||||
|
||||
## Gradle 정책 권위
|
||||
|
||||
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로,
|
||||
Gradle path, 허용 production project dependency edge. runtime membership 목록은 없다: 조립 루트가
|
||||
받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 SSOT는 registry다. 문서는 개수를 복제하지 않는다 —
|
||||
산문에 적힌 숫자는 leaf가 추가되는 순간 drift하기 때문이다. 이제 이걸 강제하는 태스크는 없다:
|
||||
`verifyDocumentedLeafCount`는 삭제됐다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬
|
||||
사유는 아니고, 그 태스크는 모든 `CLAUDE.md`와 `build.gradle`을 정규식으로 훑는 파서였다.
|
||||
- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어
|
||||
project를 include/mapping 한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖
|
||||
경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은
|
||||
`verifyCleanArchitectureDependencies`가 답한다 — settings에서 죽으면 실행할 수 있는 태스크가
|
||||
하나도 없다.
|
||||
- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나
|
||||
(`strictTestLanes`). leaf는 `ca.java-library` / `ca.spring-library` / `ca.platform-module` 중
|
||||
자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다.
|
||||
`ca.architecture`가 아키텍처 검증 태스크를 소유한다. 기능별 검사(notification·mongo·messaging·
|
||||
graphql·JPA readiness 등)는 build-logic이 아니라 소유 leaf의 테스트다. 테스트가 저장소 파일을 읽으면
|
||||
그 파일을 그 leaf의 test task `inputs`로 선언한다. 저장소 문서와 대조하는 테스트는 `mainStage()`
|
||||
레인(`document-contract` 태그)으로 leaf `mainCheck`에서 돈다. 문서가 아닌 저장소 파일(빌드 스크립트,
|
||||
workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔
|
||||
별도 레인(app-bootstrap `repository-contract`)에 둔다. 저장소 루트(`ca.repository.root`)는 이 두
|
||||
레인에만 주므로 태그 없이 저장소를 읽는 테스트는 `test`에서 실패한다.
|
||||
- strict lane 캐시: `TEST`·`ARCHITECTURE` lane은 입력이 같으면 up-to-date·build cache를 쓴다.
|
||||
`INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼
|
||||
입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을
|
||||
입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.
|
||||
- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다: convention이 테스트 JVM에
|
||||
`performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면
|
||||
테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도).
|
||||
사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
|
||||
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의
|
||||
`ca.config-contract`다. 옛 included build `build-tools`는 지웠다(`docs/capability-status.md` 「제거된 코드」).
|
||||
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
|
||||
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
|
||||
--dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는
|
||||
단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·
|
||||
`releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`·
|
||||
`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈
|
||||
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
|
||||
lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·
|
||||
`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는
|
||||
짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다.
|
||||
(1) 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는
|
||||
파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤,
|
||||
`exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`. (2) 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌
|
||||
`&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나
|
||||
부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태
|
||||
함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만
|
||||
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore`
|
||||
필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches`
|
||||
없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이
|
||||
부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는
|
||||
job.
|
||||
(3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른
|
||||
명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤,
|
||||
`bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). 실패 메시지는 명령마다 이유를
|
||||
적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서
|
||||
시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다.
|
||||
|
||||
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
|
||||
함께 읽는다. focused test는 registry의 `gradle_path`에서
|
||||
`./gradlew <gradle-path>:test --console=plain` 형태로 파생한다. 파일 수만으로 위험을 판단하지 않고,
|
||||
변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다.
|
||||
|
||||
commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다.
|
||||
예외는 하나다: brief가 허용한 것만(commit과 push는 따로) 그 작업의 자기 브랜치에 한다. main 병합,
|
||||
다른 브랜치 push, force push는 하지 않는다(`docs/work/README.md` 「커밋」).
|
||||
|
||||
## 강제 수준
|
||||
|
||||
이 문서는 에이전트와 개발자가 따라야 할 작업 규칙을 정의하지만, 그 자체로 빌드나 테스트를 실패시키는 자동 강제 장치는 아니다.
|
||||
|
||||
이 프로젝트의 규칙은 세 단계로 관리한다.
|
||||
|
||||
1. `AGENTS.md`: 에이전트와 개발자가 따라야 할 아키텍처, 작업 순서, 검증 원칙을 정의한다.
|
||||
2. ArchUnit/Gradle/Test: 모듈 의존성, 계층 침범, 설정 바인딩, 동작 회귀를 자동으로 탐지한다.
|
||||
3. Code Review/CI: 문서와 자동 검증이 놓친 설계 품질, 운영 위험, 템플릿 일관성을 최종 확인한다.
|
||||
|
||||
에이전트는 `AGENTS.md`를 따라 작업해야 하며, 현업 수준의 스켈레톤 완성도는 반드시 자동 검증과 리뷰로 보강해야 한다.
|
||||
|
||||
## 모듈 책임
|
||||
|
||||
모든 leaf 모듈의 ID, 실제 소스 경로, Gradle path, 허용 production 의존성은
|
||||
`src/config/architecture/modules.json`이 SSOT다. focused test는 소유 leaf의 `gradle_path`에서
|
||||
파생한다. 이 문서는 leaf 목록을 복제하지 않고 family 책임만 정의한다. 작업 파일에서는 가장 가까운
|
||||
`src/**/CLAUDE.md`를 함께 읽는다.
|
||||
|
||||
- `domain-core`: 순수 도메인 모델, 불변식, 이벤트, port. Spring/JPA/transport/IO 타입 금지.
|
||||
- `application-core`: command, use case, application policy, transaction port, application 예외.
|
||||
inbound DTO, persistence entity, adapter 타입 금지.
|
||||
- `adapter:inbound:*`: HTTP/gRPC/GraphQL/WebSocket transport, DTO, validation, 인증·인가 매핑,
|
||||
error mapping. repository 직접 호출과 비즈니스 정책 금지.
|
||||
- `adapter:outbound:persistence-*`: JPA/PostgreSQL 또는 MongoDB persistence 구현과 mapping,
|
||||
migration/vendor 동작. 유스케이스 정책 금지.
|
||||
- 그 밖의 `adapter:outbound:*`: support, messaging, cache, notification, object storage,
|
||||
file server, HTTP client, identifier 능력을 port 뒤에서 구현한다. adapter 간 허용 edge는
|
||||
registry만 따른다.
|
||||
- `shared-contract`: skeleton-wide 운영 계약. business/domain 개념 저장 금지.
|
||||
- `app-bootstrap`: Spring Boot entrypoint와 composition root. 비즈니스 유스케이스 금지.
|
||||
|
||||
## 의존성 방향
|
||||
|
||||
family 수준 기본 방향:
|
||||
|
||||
```text
|
||||
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
|
||||
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
|
||||
runtime modules -> shared-contract
|
||||
```
|
||||
|
||||
개별 edge는 `src/config/architecture/modules.json`의 `allowed_dependencies`가 유일한 목록이다.
|
||||
Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억에서 leaf edge를 추론하지 않는다.
|
||||
|
||||
## 기능 개발 프로토콜
|
||||
|
||||
새 기능이나 동작 변경은 다음 순서로 진행한다.
|
||||
|
||||
1. 요구사항을 읽고 소유 계층을 판단한다.
|
||||
2. 구조나 동작이 바뀌면 `superpowers:brainstorming`으로 설계를 먼저 확정한다.
|
||||
3. 여러 단계의 작업이면 `docs/design/`에 설계 문서를 남긴다. 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다.
|
||||
4. 실행 계획이 필요하면 구현 전 `docs/history/plans/`에 둔다. 계획서도 머리 블록을 단다. 머리 블록 형식은 `docs/README.md`다.
|
||||
5. 동작 변경은 테스트를 먼저 작성한다.
|
||||
6. 새 비즈니스 개념은 `domain-core`에 먼저 둔다.
|
||||
7. 유스케이스는 `application-core` command와 use case/service method로 표현한다.
|
||||
8. 외부 연동은 registry가 가리키는 `adapter:outbound:*` leaf에서 port 구현으로 추가한다.
|
||||
9. endpoint는 마지막에 해당 `adapter:inbound:*` leaf에서 얇게 연결한다.
|
||||
10. focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다.
|
||||
|
||||
단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 `docs/manual/`, 뼈대는
|
||||
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. 실제 기능은 계층 leaf별로 나눈다.
|
||||
|
||||
## 테스트 전략
|
||||
|
||||
계층별 테스트 기준:
|
||||
|
||||
- `domain-core`: Spring 없이 순수 unit test로 도메인 규칙을 검증한다.
|
||||
- `application-core`: fake/in-memory port를 사용해 유스케이스 흐름을 검증한다.
|
||||
- `adapter:inbound:*`: transport validation, auth mapping, status/response contract를 검증한다.
|
||||
- `adapter:outbound:persistence-*`: persistence mapping, repository adapter, vendor/migration 동작을 검증한다.
|
||||
- 그 밖의 `adapter:outbound:*`: external capability adapter contract를 검증한다.
|
||||
- `app-bootstrap/settings`: configuration binding, validation, logging 설정을 검증한다.
|
||||
|
||||
테스트 작성 규칙 (새로 쓰거나 고치는 테스트에 적용):
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
|
||||
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로
|
||||
쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
|
||||
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할
|
||||
것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다.
|
||||
예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때
|
||||
`// when & then`까지 허용). 한 줄 테스트와 ArchUnit `.check()`는 주석 없이 쓴다.
|
||||
4. `@Nested`는 테스트 10개 이상이고 대상 연산이 2개 이상인 클래스에서만, 연산 단위로 한 단계만 쓴다.
|
||||
5. then은 when의 결과 하나만 단언한다. 여러 필드는 `usingRecursiveComparison()` 또는
|
||||
`extracting(..).containsExactly(..)`로 한 번에 비교한다. `isNotNull`/`isPresent`/
|
||||
`doesNotThrowAnyException`만으로 끝내지 않는다(이름이 "예외 없음" 자체를 말할 때만 예외).
|
||||
예외는 타입과 reason/message를 함께 단언한다. 표 형태 입력은 `@ParameterizedTest`로 쓴다.
|
||||
6. 포트 대역은 hand-rolled fake를 포트당 하나, 포트 소유 모듈 testFixtures에 둔다. adapter가 있는
|
||||
포트는 fake와 adapter가 같은 추상 계약 테스트(`XxxContract`)를 통과한다. Mockito는 프레임워크
|
||||
경계(Spring Data repository, SDK client)와 장애 주입에만 쓴다.
|
||||
|
||||
GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없어 ArchUnit이 볼 수 없고,
|
||||
실질적인 강제 수단은 fake와 adapter가 같은 계약 테스트를 상속하는 구조다.
|
||||
|
||||
검증 원칙:
|
||||
|
||||
- 완료를 주장하기 전에 `superpowers:verification-before-completion`을 사용한다.
|
||||
- 실행한 명령과 결과를 최종 응답에 적는다.
|
||||
- 테스트를 실행하지 못했다면 이유와 남은 위험을 솔직히 적는다.
|
||||
|
||||
권장 절차:
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew <owner-gradle-path>:check --console=plain # 그 leaf만: 컴파일·테스트·포맷·스타일·ErrorProne
|
||||
./gradlew check # 모든 leaf의 check
|
||||
./gradlew architectureCheck # 의존 방향·domain-core/shared-contract/application-* 순수성·ArchUnit
|
||||
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
|
||||
./gradlew testQualityCheck # 같은 분석을 테스트 source set에(config/spotbugs/exclude-test.xml, main 단계·optional 빌드는 ci)
|
||||
./gradlew ci # PR 게이트 = leaf check + architecture + quality
|
||||
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
|
||||
./gradlew integrationCheck # 실제 컨테이너 integration 레인 전체(main·nightly, Docker 필요)
|
||||
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly). 상한은 항상 단언, 끄면 실패
|
||||
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p platforms/optional-build로 따로)
|
||||
./gradlew verifyPublicPathSnapshot
|
||||
./gradlew :app-bootstrap:verifyEnvKeys
|
||||
```
|
||||
|
||||
leaf의 `check`는 그 leaf만 검사한다. 저장소 전체 질문은 이름이 따로 있는 루트 태스크가 답한다.
|
||||
|
||||
소유 leaf의 정확한 Gradle path는 `src/config/architecture/modules.json`에서 읽고 focused test
|
||||
명령을 파생한다. root 문서에 leaf별 명령 목록을 복제하지 않는다.
|
||||
|
||||
## 부가 기능(capability) 모듈 규칙
|
||||
|
||||
Redis, Kafka, JPA 같은 부가 기능은 "의존성을 붙이면 켜지고, 떼면 사라지는 모듈"로 제공한다.
|
||||
각 서비스는 `app-bootstrap/build.gradle`에 필요한 모듈만 `runtimeOnly` 한 줄로 고른다.
|
||||
설계 근거는 `docs/design/2026-09-25-capability-module-packaging-design.md`.
|
||||
|
||||
템플릿 기본 조립은 web에서 쓰는 부분뿐이다: `adapter:inbound:web`, 운영 관측(actuator·metrics·
|
||||
tracing·로그), `domain-core`·`application-core`·`shared-contract`, `adapter:outbound:support`·
|
||||
`adapter:outbound:identifier`. 그 밖의 기능(JPA 포함)은 한 줄을 추가해서 켠다.
|
||||
|
||||
capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
|
||||
|
||||
1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다.
|
||||
2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled`
|
||||
설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 명시한다(`afterName`).
|
||||
3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키
|
||||
자체를 두지 않는다.
|
||||
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact
|
||||
constructor에서 한다.
|
||||
예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
|
||||
`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중
|
||||
하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/CLAUDE.md`.
|
||||
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두
|
||||
통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
|
||||
6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
|
||||
7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 스위치 목록에 등록하지
|
||||
않고, 한 줄을 지우면 기능이 완전히 사라진다.
|
||||
|
||||
모듈 설정 기본값은 `config/module-defaults/<모듈>.yml`에 두고 `adapter:outbound:support`의
|
||||
`ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. 의존성 closure에 support가 없는 leaf
|
||||
(persistence-mongo, graphql)만 자기 EPP가 `config/<이름>.yml`을 읽는다.
|
||||
|
||||
서비스 코드가 모듈 타입을 직접 호출해야 하는 라이브러리형 기능은 `runtimeOnly`로 컴파일되지
|
||||
않는다. 그런 기능은 가능한 한 포트 뒤로 옮기고, 불가피하면 서비스의 어댑터 leaf에서
|
||||
`implementation`으로 받는다.
|
||||
|
||||
## 설정과 런타임
|
||||
|
||||
설정 규칙:
|
||||
|
||||
- secrets를 코드, 테스트 fixture, 문서 예시에 하드코딩하지 않는다.
|
||||
- 새 설정 그룹은 typed settings class로 만든다.
|
||||
- 흩어진 `@Value`보다 configuration properties와 settings class를 선호한다.
|
||||
- `.env.local`은 로컬 오버라이드로 취급한다.
|
||||
- `application.yml`은 환경별로 안전한 기본값과 명확한 placeholder만 담는다.
|
||||
- 새 settings class를 만들면 binding/validation 테스트를 추가한다.
|
||||
|
||||
Docker/runtime 규칙:
|
||||
|
||||
- Dockerfile 변경 시 build context와 runtime env 요구사항을 함께 확인한다.
|
||||
- container 안에서 필요한 profile, port, env var를 문서나 예시 설정에 반영한다.
|
||||
- local-only 경로와 운영 경로를 섞지 않는다.
|
||||
|
||||
## 템플릿 재사용 체크리스트
|
||||
|
||||
이 저장소를 새 프로젝트 시작점으로 사용할 때:
|
||||
|
||||
1. `src/settings.gradle`의 `rootProject.name`을 새 프로젝트명으로 바꾼다.
|
||||
2. Java package `dev.caskeleton`을 새 organization/project package로 바꾼다.
|
||||
gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/`의
|
||||
디렉터리, 각 `.proto`의 `package`·`java_package`)도 함께 바꾸고 `buf lint`로 확인한다.
|
||||
3. `CaSkeletonApplication` 이름을 새 애플리케이션 이름으로 바꾼다.
|
||||
4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가한다.
|
||||
5. 모듈 이름과 경계는 유지한다.
|
||||
6. Docker image/application 이름을 새 프로젝트 기준으로 수정한다.
|
||||
7. `.env`, `.env.local`, `application.yml`의 예시 값을 새 런타임 요구사항에 맞춘다.
|
||||
8. README와 운영 문서를 새 프로젝트 설명으로 갱신한다.
|
||||
9. 전체 테스트를 실행한다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew test
|
||||
```
|
||||
|
||||
## 금지된 지름길
|
||||
|
||||
에이전트는 다음을 하지 않는다.
|
||||
|
||||
- `domain-core`에 Spring/JPA annotation 추가
|
||||
- controller에서 repository 직접 호출
|
||||
- application method가 web request DTO를 인자로 받게 만들기
|
||||
- application이나 domain에서 JPA entity 반환
|
||||
- mapper에 비즈니스 정책 넣기
|
||||
- filter/config/settings class에 유스케이스 넣기
|
||||
- 요청 범위 밖의 대규모 리팩터링
|
||||
- 사용자 변경사항 되돌리기
|
||||
- 명시적 요청 없는 destructive git command 실행
|
||||
- 테스트 미실행 상태에서 "완료"라고 말하기
|
||||
|
||||
## 작업 보고 규칙
|
||||
|
||||
최종 응답에는 다음을 포함한다.
|
||||
|
||||
- 변경한 파일
|
||||
- 핵심 변경 내용
|
||||
- 실행한 검증 명령
|
||||
- 실패하거나 실행하지 못한 검증
|
||||
- 남은 위험 또는 후속 작업
|
||||
|
||||
짧은 작업이라도 검증 여부는 생략하지 않는다.
|
||||
- 커밋 정책은 `human-only`다. brief가 허용한 것만 자기 브랜치에 한다(`docs/work/README.md` 4절).
|
||||
- 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
|
||||
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(`docs/work/delegate.md`).
|
||||
|
||||
@@ -1,75 +1,9 @@
|
||||
# CLAUDE.md — 이 repo의 지도
|
||||
@AGENTS.md
|
||||
|
||||
이 파일은 세션이 처음 읽는 지도다. 규칙을 담지 않고, 어떤 일이면 무엇을 읽을지 가리킨다.
|
||||
## Claude Code에서만
|
||||
|
||||
## 1. 이 repo
|
||||
|
||||
- Java 21 + Spring Boot Gradle 멀티모듈(버전은 `src/gradle/libs.versions.toml`) Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다.
|
||||
- Gradle 루트는 `src/`다. Gradle 명령은 `src/`에서 실행한다.
|
||||
- 규칙의 정본은 `AGENTS.md`다. leaf 목록·경로·허용 의존의 정본은 `src/config/architecture/modules.json`(registry)이다. 각 leaf의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`가 정한다.
|
||||
|
||||
## 2. HARD-STOP — 하나라도 어기면 완료가 아니다
|
||||
|
||||
정본은 `AGENTS.md` 「Prime Directive」다. 두 문서가 다르면 `AGENTS.md`가 맞다.
|
||||
|
||||
1. `domain-core`가 framework·transport·database·cloud 의존성을 가진다.
|
||||
2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
|
||||
3. inbound DTO가 `application-core`나 `domain-core`로 들어간다.
|
||||
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
|
||||
5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
|
||||
6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
|
||||
7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
|
||||
|
||||
## 3. 맡은 일 → 읽을 문서
|
||||
|
||||
먼저 [docs/work/README.md](docs/work/README.md)를 읽는다. 크기 정하기, 모든 작업의 공통 단계, 커밋 규칙이 거기 있다. 그다음 맡은 일의 playbook 하나를 끝까지 읽는다.
|
||||
|
||||
| 맡은 일 | playbook |
|
||||
| --- | --- |
|
||||
| 새 업무 기능, 새 capability 모듈 | [docs/work/new-feature.md](docs/work/new-feature.md) → `docs/manual/` |
|
||||
| 리뷰, 결함 수정, 리팩터링, 성능, 구조·테스트 구조 개선 | [docs/work/improve.md](docs/work/improve.md) |
|
||||
| 바꾸기 전에 대안 비교와 소유자 결정 | [docs/work/research-design.md](docs/work/research-design.md) |
|
||||
| 매뉴얼·안내 문서 쓰기 | [docs/work/docs-writing.md](docs/work/docs-writing.md) |
|
||||
| 게이트 실행, desktop 검증, 릴리스, 파생 서비스 | [docs/work/operate.md](docs/work/operate.md) |
|
||||
| 큰 일을 나눠 다른 세션에 맡기기 | [docs/work/delegate.md](docs/work/delegate.md) |
|
||||
|
||||
brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 먼저다. playbook은 brief에 없는 공통 절차를 채운다.
|
||||
|
||||
## 4. 검증 명령과 실행 위치
|
||||
|
||||
- **실행 위치**: 소유자 환경에서는 Gradle·Docker·테스트·게이트를 desktop에서만 돌린다. 절차는 [docs/work/operate.md](docs/work/operate.md) 4.1절이다.
|
||||
- **leaf 하나**: registry에서 그 leaf의 `gradle_path`를 읽고 `./gradlew <gradle-path>:test --console=plain` 또는 `:check`를 돌린다. 기억이나 디렉터리 이름으로 Gradle path를 짐작하지 않는다.
|
||||
- **저장소 전체 질문**:
|
||||
|
||||
```bash
|
||||
./gradlew architectureCheck --console=plain
|
||||
./gradlew :app-bootstrap:architectureTest --console=plain
|
||||
./gradlew verifyPublicPathSnapshot --console=plain
|
||||
./gradlew :app-bootstrap:verifyEnvKeys --console=plain
|
||||
```
|
||||
|
||||
- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다.
|
||||
- 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다.
|
||||
- `docs/work/`, 이 파일, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다(분량, 본문 이력 ID 0, 상대 링크).
|
||||
- 문서(`.md`)나 문서가 가리키는 경로·Gradle 프로젝트를 바꿨으면 `python3 scripts/check-docs.py`를 돌린다(언어, 기록의 머리 블록, 참조, 복사한 숫자). PR마다 `docs-check` workflow가 같은 검사를 돈다. 규칙은 [docs/README.md](docs/README.md)다.
|
||||
|
||||
## 5. 코드만 보고는 헷갈리는 곳
|
||||
|
||||
- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. `scripts/check-repo-layout.py`(PR 게이트)가 허용 목록 밖의 최상위 항목을 막는다.
|
||||
- **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다.
|
||||
- **`src/platforms/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/platforms/messaging/CLAUDE.md`다.
|
||||
- **`composition:*` leaf는 조립만 한다.** outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 `runtimeOnly` 한 줄로 고른다.
|
||||
- **capability는 한 줄로 켜고 끈다.** 기본 조립은 web inbound, 운영 관측, core들, support·identifier뿐이다. JPA도 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켠다. 규칙은 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」이다.
|
||||
- **gRPC 플랫폼 라이브러리는 다른 빌드다.** `src/platforms/grpc/*`·`src/platforms/grpc-advanced/*`(registry의 `"build": "optional-grpc"`)는 `-p platforms/optional-build`로 돈다. `adapter:inbound:grpc`는 애플리케이션 adapter라 주 빌드에 있다.
|
||||
- **새 기능의 예시는 `scripts/new-feature.sh`의 출력이다.** 샘플 모듈은 2026-11-07에 지웠다. 기법 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)를 가리킨다.
|
||||
- **성능 lane에는 단언을 끄는 스위치가 없다.** convention이 상한을 매번 단언하고, `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(`AGENTS.md` 「Gradle 정책 권위」).
|
||||
- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow를 읽는 테스트는 `repository-contract`(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다.
|
||||
- **커밋 정책은 `human-only`다.** brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다.
|
||||
- **문서 위치 규칙은 [docs/README.md](docs/README.md)다.** 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 고치지 않는 기록(계획서·납품 패키지·증거·학습)은 `docs/history/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다. 기록은 맨 위 머리 블록만 고친다.
|
||||
|
||||
## 6. 소유자 환경
|
||||
|
||||
- 이 repo 소유자의 기계·세션 도구에 묶인 규칙은 두 곳에만 있다: [docs/work/operate.md](docs/work/operate.md) 4.1절(실행 위치)과 [docs/work/delegate.md](docs/work/delegate.md) 4.3절(세션). 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다.
|
||||
- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 일을 나눌 때는 delegate.md대로 별도 세션에 맡긴다.
|
||||
- 작업 사고 순서의 정본은 design-docs `conventions/work-thinking-order.md`, 커밋·PR 형식은 `conventions/commit-and-pr.md`다.
|
||||
- 보고 말투와 형식은 소유자의 전역 `~/.claude/CLAUDE.md`를 따른다.
|
||||
- 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다.
|
||||
- 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다.
|
||||
- 스킬은 `.claude/skills/`다: `new-feature`(새 기능), `desktop-gates`(Gradle·Docker를 desktop에서). 발동 조건이 설명에 있어 모델이 부른다.
|
||||
- 서브에이전트는 `.claude/agents/`다: `arch-reviewer`(구조 리뷰), `verify-api`(desktop에서 앱 띄워 확인), `code-simplifier`(단순화 제안). 모두 결과만 돌려주고 파일을 고치지 않는다.
|
||||
- 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다.
|
||||
|
||||
@@ -74,7 +74,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
|
||||
- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다.
|
||||
- 줄마다 필요한 env 키와 끄는 키: [src/README.md](src/README.md) 「기능 추가 = 한 줄 + env」 표.
|
||||
- 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md).
|
||||
- capability 모듈이 지켜야 하는 규칙: [AGENTS.md](AGENTS.md) 「부가 기능(capability) 모듈 규칙」.
|
||||
- capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: [docs/manual/10-capabilities.md](docs/manual/10-capabilities.md).
|
||||
|
||||
뒷단 서비스는 `compose.yaml`의 profile로 고른다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있다.
|
||||
|
||||
@@ -84,7 +84,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
|
||||
|
||||
| 하려는 일 | 시작할 곳 |
|
||||
| --- | --- |
|
||||
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [CLAUDE.md](CLAUDE.md) |
|
||||
| 이 저장소에서 일하기(새 기능, 개선, 조사, 문서, 운영, 일 나누기) | 작업 매뉴얼 [docs/work/README.md](docs/work/README.md). 지도는 [AGENTS.md](AGENTS.md) |
|
||||
| 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` |
|
||||
| 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` |
|
||||
| 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` |
|
||||
@@ -92,7 +92,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
|
||||
| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
|
||||
| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` |
|
||||
|
||||
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `CLAUDE.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)).
|
||||
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)).
|
||||
|
||||
## 검증
|
||||
|
||||
@@ -110,7 +110,7 @@ cd src
|
||||
|
||||
## 새 서비스로 시작하기
|
||||
|
||||
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 전체 체크리스트는 [AGENTS.md](AGENTS.md) 「템플릿 재사용 체크리스트」다.
|
||||
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
|
||||
|
||||
1. `src/settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
|
||||
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
|
||||
@@ -122,6 +122,10 @@ cd src
|
||||
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다.
|
||||
4. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
|
||||
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
|
||||
6. gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`도 바꾼다. `src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/` 디렉터리와 각 `.proto`의 `package`·`java_package`다. `buf lint`로 확인한다.
|
||||
7. Docker 이미지 이름과 애플리케이션 이름(`spring.application.name`)을 새 서비스 기준으로 바꾼다.
|
||||
8. `src/.env.example`, `src/.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다.
|
||||
9. README와 운영 문서를 새 서비스 설명으로 고친다.
|
||||
|
||||
복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`).
|
||||
|
||||
@@ -129,7 +133,7 @@ cd src
|
||||
|
||||
## 규칙과 기여
|
||||
|
||||
- 규칙의 정본은 [AGENTS.md](AGENTS.md)다. 「Prime Directive」의 HARD-STOP 조건을 어기면 동작하더라도 병합하지 않는다.
|
||||
- 일을 시작할 때 읽는 지도는 [CLAUDE.md](CLAUDE.md)다. 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
|
||||
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`다.
|
||||
- 규칙의 정본이자 일을 시작할 때 읽는 지도는 [AGENTS.md](AGENTS.md)다. 「HARD-STOP」 조건을 어기면 동작하더라도 병합하지 않는다. Claude Code 세션은 [CLAUDE.md](CLAUDE.md)가 이 파일을 가져온다.
|
||||
- 일의 종류별 절차는 [docs/work/README.md](docs/work/README.md)다.
|
||||
- 각 모듈의 지역 규칙은 가장 가까운 `src/**/AGENTS.md`다.
|
||||
- 커밋 정책과 메시지 형식은 [docs/work/README.md](docs/work/README.md) 「커밋」이다. PR은 [.github/pull_request_template.md](.github/pull_request_template.md) 양식을 채운다.
|
||||
|
||||
+18
-5
@@ -19,8 +19,9 @@
|
||||
|
||||
| 폴더 | 무엇 |
|
||||
| --- | --- |
|
||||
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 |
|
||||
| `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 실행 계층 |
|
||||
|
||||
### 계약과 스냅숏
|
||||
@@ -139,7 +140,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서,
|
||||
`history/evidence/`·`history/plans/evidence/` 증거, `history/packages/` 납품 패키지,
|
||||
`history/study/` 학습 문서. ADR의 둘째 줄은
|
||||
`> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다.
|
||||
`> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다.
|
||||
- 상태는 종류마다 고정 어휘다.
|
||||
|
||||
| 종류 | 상태 |
|
||||
@@ -158,6 +159,16 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
`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`(지역 규칙), 영역 운영 문서
|
||||
|
||||
## 문서와 코드를 같은 변경에서 고친다
|
||||
|
||||
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법:
|
||||
@@ -172,7 +183,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
|
||||
## 문서 검사
|
||||
|
||||
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여섯을 본다. PR마다 workflow `docs-check`가
|
||||
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 workflow `docs-check`가
|
||||
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
|
||||
문서를 낡게 만든다.
|
||||
|
||||
@@ -184,6 +195,8 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
| `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/`)는 테스트가 읽는 입력이라 문서로 보지 않는다.
|
||||
@@ -193,11 +206,11 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
|
||||
- 줄을 지우면 같은 변경에서 `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`가 본다.
|
||||
- 상대 링크는 `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/**/CLAUDE.md` 가 소유한다.
|
||||
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-09-07
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-24
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-31
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-11
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-24
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-13
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-25
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-14
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택(보완)
|
||||
- 작성일: 2026-08-15
|
||||
|
||||
@@ -32,6 +32,9 @@
|
||||
| `dependency-vulnerability.yml` | dependency-review + Trivy |
|
||||
| `ci-quality-gates.yml` | PR 게이트 |
|
||||
| `release.yml` | 이미지 · SBOM 생산 |
|
||||
| `docs-check.yml` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) |
|
||||
| `link-check.yml` | 문서의 외부 URL과 상대 링크(lychee) |
|
||||
| `scripts/check-repo-layout.py`(`ci-quality-gates.yml` 안) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 |
|
||||
| action의 full SHA 핀 | 공급망 |
|
||||
|
||||
## 파생 프로젝트가 할 일
|
||||
|
||||
@@ -48,7 +48,7 @@ major의 증거가 모두 같은 커밋 SHA를 지니기를 요구한다. 그래
|
||||
H2는 두 번째 운영 대상이 아니다. 같은 위반에 다른 SQLSTATE를 보고하고, JSONB 연산자도, range 타입도, 동시 인덱스
|
||||
빌드도 없다. H2에서 통과한 실행은 코드가 컴파일되고 돈다는 증거일 뿐이다.
|
||||
|
||||
`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `CLAUDE.md`는 측정을 기록한다.
|
||||
`SKIP LOCKED`는 따로 한 문장이 필요하다. 두 문서가 다른 말을 했기 때문이다. 모듈의 `AGENTS.md`는 측정을 기록한다.
|
||||
H2 2.4.240은 `FOR UPDATE SKIP LOCKED`를 받고 잠긴 행을 정말로 건너뛴다. 그래서 outbox claim SQL이 두 vendor에서 같다. 이
|
||||
문서는 전에 H2에 그런 보장이 없다고 했다. 둘은 서로 다른 질문에 각각 맞았고, 그 구별이 요점이다. **측정한 버전에서 관찰한
|
||||
동작은 운영 보장이 아니고, PostgreSQL 계약 증거는 더욱 아니다.** 측정 덕분에 claim SQL에 vendor 분기가 필요 없고, 보장이
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
# 예측·실측 장부
|
||||
|
||||
작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07).
|
||||
|
||||
```text
|
||||
착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거
|
||||
끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측
|
||||
회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계
|
||||
```
|
||||
|
||||
- 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다.
|
||||
- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다.
|
||||
- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다.
|
||||
- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다.
|
||||
- 위임 대조용 장부(design-docs `delegation-loop/ledger.jsonl`)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의 `task`를 가리킨다.
|
||||
|
||||
## 줄의 칸
|
||||
|
||||
모든 줄:
|
||||
|
||||
| 칸 | 형식 | 뜻 |
|
||||
| --- | --- | --- |
|
||||
| `schema` | 정수 | 이 형식의 판. 지금 1 |
|
||||
| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 |
|
||||
| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) |
|
||||
| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 |
|
||||
| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects/<cwd>/<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 |
|
||||
|
||||
`estimate`:
|
||||
|
||||
| 칸 | 형식 | 뜻 |
|
||||
| --- | --- | --- |
|
||||
| `started_at` | ISO 8601 | 세션 첫 기록 시각 |
|
||||
| `base` | 문자열 | 기준 커밋 |
|
||||
| `task_kind`, `size` | 문자열 | `docs/work/` playbook 이름, 작음·중간·큼(`small`·`medium`·`large`) |
|
||||
| `minutes`, `calls`, `output_tokens` | `{"p30","p50","p80"}` 정수 | 작업 중 시간(분), 모델 호출 수, 출력 토큰 |
|
||||
| `basis` | 문자열 | 근거: 비교한 선례와 그 실측, 바꿀 파일 수, 검증 대기 |
|
||||
|
||||
`actual`:
|
||||
|
||||
| 칸 | 형식 | 뜻 |
|
||||
| --- | --- | --- |
|
||||
| `minutes`, `active_minutes` | 정수 | 벽시계 시간, 작업 중 시간(세션 기록 사이 빈틈을 5분까지만 더한 시간. 긴 대기와 다음 지시를 기다린 시간이 빠진다) |
|
||||
| `calls`, `output_tokens`, `cache_read_tokens`, `max_context` | 정수 | 세션 기록 assistant 줄의 `message.usage`. 같은 `message.id`는 한 번만 센다 |
|
||||
| `within` | 문자열 | `p30`·`p50`·`p80`·`over`: 시간 실측이 들어간 가장 작은 예측 |
|
||||
| `result`, `commits` | 문자열, 배열 | 완료·부분·못 함, 만든 커밋 |
|
||||
| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 |
|
||||
|
||||
`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서).
|
||||
@@ -0,0 +1,2 @@
|
||||
{"schema": 1, "kind": "estimate", "task": "h3-backend-harness", "recorded_at": "2026-11-07T21:46+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "started_at": "2026-11-07T21:37:50+09:00", "base": "b3f63be6", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 150, "p50": 210, "p80": 300}, "calls": {"p30": 450, "p50": 600, "p80": 850}, "output_tokens": {"p30": 450000, "p50": 600000, "p80": 850000}, "basis": "선례 h1-harness-design 작업 중 23분·호출 100·출력 13.6만(바꾼 파일 3, Gradle 없음)에서 분당 호출 4.3, 호출당 출력 1,400. 이번에 바꿀 파일 약 120(하위 문서 이동 28, 새 CLAUDE.md 32, 문서의 AGENTS.md 참조 93줄, 검사기 2, 훅 6, 시험 3, Java 테스트 3, 에이전트·스킬·규칙 8), 매뉴얼 항목 약 60(선례 manual-gap-fix-2가 52건을 한 세션에), desktop 대기 30~50분"}
|
||||
{"schema": 1, "kind": "actual", "task": "h3-backend-harness", "recorded_at": "2026-11-07T23:13+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "minutes": 94, "active_minutes": 68, "calls": 270, "output_tokens": 345525, "cache_read_tokens": 132822591, "max_context": 805096, "within": "p30", "result": "done", "commits": ["08f93212", "3c73fc33", "38891071", "c67c7131", "67ecae2c", "37c88fed", "59dff004", "c8db79a7", "d9059806", "7140f279", "93b70b06", "248df518"], "why": "모든 값이 p30보다 작았다. 바꿀 파일 수(약 120, 실제 190여)를 호출 수로 옮겼는데, 이동·참조 수정 수십 파일을 스크립트 한 번으로 묶어 파일당 호출이 거의 없었다. desktop 대기는 예측과 비슷했지만(합친 트리 한 번 27분, 중단한 두 번) 작업 중 시간에서는 빈틈마다 5분으로 잘린다. 다음 예측은 파일 수가 아니라 손으로 판단할 결정 수(이번 약 25)와 desktop 실행 횟수를 근거로 쓴다. 실측은 23:12까지의 세션 기록이고, 뒤의 커밋·PR·보고는 들어 있지 않다"}
|
||||
@@ -30,7 +30,7 @@ scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에
|
||||
| 입력 | 규칙 | 어디서 막나 |
|
||||
| --- | --- | --- |
|
||||
| 이름 | PascalCase, 영숫자 | 스크립트 |
|
||||
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
|
||||
| 패키지 이름 | 이름을 소문자로(`purchaseorder`). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(`operation`, `lock`, `cache`…)가 모두 여기 걸린다. 목록은 `src/application-core/AGENTS.md` 「Package ownership」 | 스크립트, `NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES` |
|
||||
| HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, `ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122` |
|
||||
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
|
||||
|
||||
@@ -79,7 +79,7 @@ verify-feature-scaffold.sh
|
||||
| 형태 | 결정 | 이유 |
|
||||
| --- | --- | --- |
|
||||
| `scripts/`의 bash + 텍스트 템플릿(`scripts/feature-scaffold/templates/**/*.tmpl`) | **채택** | 개발자 도구는 `scripts/`에 둔다는 repo 관례(`ca.developer-bootstrap` 플러그인을 지우고 `scripts/bootstrap-local.sh`로 옮긴 것, `src/build-logic/README.md`). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다 |
|
||||
| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`CLAUDE.md` Gradle policy). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
|
||||
| build-logic의 Gradle 태스크(`./gradlew newFeature -Pname=…`) | 버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(`src/build-logic/AGENTS.md`). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
|
||||
| 생성 대신 예시 기능을 커밋해 두고 복사 | 버림 | 복사본이 하나 더 생겨 규칙과 갈라진다. 이름 바꾸기를 사람이 손으로 한다 |
|
||||
| 왕복 검사를 JUnit 안에서 javac로 컴파일 | 버림 | Spotless·Error Prone·ArchUnit 전체를 다시 구현해야 하고, 실제 게이트와 다른 것을 검사하게 된다. 실제 Gradle 게이트를 그대로 돌리는 쪽을 골랐다 |
|
||||
| 생성 뒤 자동 `spotlessApply` | 채택(끄려면 `--no-format`) | google-java-format이 Javadoc을 이름 길이에 따라 다시 접는다. 템플릿만으로는 모든 이름에서 포맷 검사를 통과시킬 수 없다 |
|
||||
@@ -90,7 +90,7 @@ verify-feature-scaffold.sh
|
||||
|
||||
| 파일 | 설정 | 왜 |
|
||||
| --- | --- | --- |
|
||||
| `src/domain-core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(AGENTS.md 테스트 규칙 6) |
|
||||
| `src/domain-core/build.gradle` | `java-test-fixtures` | domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(`.claude/rules/java-tests.md` 규칙 6) |
|
||||
| `src/application-core/build.gradle`, `src/adapter/inbound/web/build.gradle`, `src/app-bootstrap/build.gradle` | `testImplementation testFixtures(project(':domain-core'))` | 유스케이스·HTTP·조립 테스트가 그 fake를 쓴다 |
|
||||
| `src/adapter/inbound/web/build.gradle` | `implementation project(':domain-core')` | 컨트롤러가 경로 문자열을 도메인 id로 바꾼다 |
|
||||
| `src/adapter/outbound/identifier/build.gradle` | `implementation project(':domain-core')` | id adapter가 도메인 `IdFactory` 포트를 구현한다 |
|
||||
|
||||
@@ -50,7 +50,7 @@
|
||||
- **기본값**: aggregate를 통째로 저장·로드하면 domain 소유 `XRepository`.
|
||||
- **예외**: 읽기 모양이 aggregate와 다르면 application 소유 `XQueryPort` + projection(record).
|
||||
`QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 반환 타입을 검사한다. lease·claim 같은 기술
|
||||
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/CLAUDE.md`.
|
||||
저장은 application 소유 `*StorePort`. 이름 규칙의 정본은 `src/application-core/AGENTS.md`.
|
||||
|
||||
## 2단계 — application-core: 유스케이스와 포트
|
||||
|
||||
@@ -70,7 +70,7 @@ record, 오류 코드 enum과 carrier 예외. 예: `src/application-core/src/mai
|
||||
- **고르는 기준**: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
|
||||
- **기본값**: 쓰기 `tx.inWrite`, 읽기 `tx.inRead`.
|
||||
- **예외**: 커밋 확인 뒤 결과를 노출해야 하면 `inRootWrite`(바깥 트랜잭션이 있으면 거부). 감사·보상만
|
||||
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/CLAUDE.md`
|
||||
`inNew`(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: `src/application-core/AGENTS.md`
|
||||
「Allowed transactional shapes」.
|
||||
|
||||
### 판단: 무엇을 반환하나
|
||||
|
||||
@@ -32,7 +32,7 @@
|
||||
- **기본값**: ①. 업무 기능은 그 서비스의 존재 이유라 끌 일이 없다. 파일 추가만으로 끝나고, leaf 경계
|
||||
검사가 계층마다 걸린다.
|
||||
- **예외**: ② — 여러 서비스가 쓰는 플랫폼 기능, 배포마다 켜고 끄는 기능, 자기 설정 prefix와 자기
|
||||
저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(`AGENTS.md`, 10장).
|
||||
저장소를 가진 기능. 이때는 capability 완료 기준 7개를 모두 지킨다(10장).
|
||||
- **다시 볼 조건**: 파생 서비스가 둘 이상 생겨 같은 업무 기능을 공유하거나, application-core 컴파일·테스트
|
||||
시간이 문제가 되면 ①을 ②로 옮긴다.
|
||||
|
||||
@@ -55,8 +55,8 @@
|
||||
- `<f>`는 템플릿 패키지 이름(`operation`, `outbox`, `lock`, `cache`, `secret`, `notification`…)과
|
||||
겹치지 않는다. 겹치면 upstream 템플릿을 받을 때 같은 패키지 트리에서 병합 충돌이 난다. 업무 코드를
|
||||
이름이 맞아 보이는 템플릿 패키지에 넣지도 않는다.
|
||||
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/CLAUDE.md`
|
||||
「Package ownership」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성
|
||||
- **어느 패키지가 템플릿 소유인지와 이 규칙의 정본은 `src/application-core/README.md`
|
||||
「패키지 소유 (Package ownership)」이다.** 매뉴얼은 목록을 다시 적지 않는다. 생성 명령이 이름을 거절하고, 생성
|
||||
뒤에는 ArchUnit(`NamingConventionTest`의 package ownership 규칙 두 개)이 다시 막는다.
|
||||
- 이름 규칙은 같은 파일 「Naming convention」이 정본이다.
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false)
|
||||
```
|
||||
|
||||
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/CLAUDE.md` 「Idempotency (KEYED)」
|
||||
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application-core/README.md` 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」
|
||||
(executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명).
|
||||
|
||||
## 판단: 이 쓰기를 KEYED로 만드나
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 핵심
|
||||
|
||||
테스트 규칙의 정본은 `AGENTS.md` 「테스트 전략」이다. 이 장은 새 기능을 만들 때 그 규칙이 **어떤
|
||||
테스트 작성 규칙의 정본은 `.claude/rules/java-tests.md`이고, 계층별로 무엇을 검증하는지는 그 계층의 `AGENTS.md` 「테스트」 절이다. 이 장은 새 기능을 만들 때 그 규칙이 **어떤
|
||||
파일 배치가 되는지**와 **어느 단계(PR/main/integration)에서 도는지**를 적는다.
|
||||
|
||||
```text
|
||||
@@ -30,7 +30,7 @@ fake와 실제 adapter가 **같은 계약**을 통과해야 fake 위의 유스
|
||||
| inbound | HTTP status·Envelope·오류 코드 | 실제 유스케이스 + fake, standalone MockMvc | `<F>ControllerTest` |
|
||||
| bootstrap | 조립 조건(있을 때 켜짐, 없을 때 없음), imports 등록 | fake bean | `<F>ConfigTest` |
|
||||
|
||||
## 작성 규칙 요약 (정본은 AGENTS.md)
|
||||
## 작성 규칙 요약 (정본은 `.claude/rules/java-tests.md`)
|
||||
|
||||
1. 이름은 lowerCamelCase 행동 문장. 이름이 말한 성질을 단언한다. 예: 이름에 "트랜잭션 전에"를 넣었으면
|
||||
트랜잭션이 없었다는 것도 단언하거나, 이름에서 뺀다.
|
||||
|
||||
@@ -17,7 +17,7 @@ use case ── tx.inWrite ─┬─▶ repository.save(aggregate) ┐
|
||||
DB 저장과 broker 발행을 따로 하면(dual write) 둘 중 하나만 성공하는 순간이 생긴다. outbox는 그 순간을
|
||||
없앤다. 대가는 **적어도 한 번** 전달이다 — 소비자는 event id로 중복을 걸러야 한다.
|
||||
|
||||
정본: `src/application-core/CLAUDE.md`(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
|
||||
정본: `src/application-core/README.md` 「계약 타입」(이벤트 타입 표), `docs/messaging/outbox-inbox.md`,
|
||||
`docs/messaging/delivery-guarantees.md`.
|
||||
|
||||
## 순서
|
||||
|
||||
@@ -17,7 +17,7 @@ app-bootstrap/build.gradle
|
||||
기능 XConfig의 @ConditionalOnBean(포트) → 유스케이스·엔드포인트가 켜진다
|
||||
```
|
||||
|
||||
정본: `AGENTS.md` 「부가 기능(capability) 모듈 규칙」(완료 기준 7개),
|
||||
이 장이 capability 규칙과 완료 기준 7개의 정본이다. 설계 근거는
|
||||
`docs/design/2026-09-25-capability-module-packaging-design.md`, 현황은 `docs/capability-status.md`.
|
||||
|
||||
## 켜기
|
||||
@@ -49,11 +49,23 @@ app-bootstrap/build.gradle
|
||||
| 1 | 서비스는 포트만 호출 | `runtimeOnly`로 컴파일되는가 |
|
||||
| 2 | 자기 `AutoConfiguration.imports`, 필요하면 `enabled` 스위치, 순서는 `afterName` | 모듈 자동 설정 테스트 |
|
||||
| 3 | 켜면 완전히 동작. 동작하지 않는 설정 키는 두지 않는다 | 설정 바인딩 테스트 |
|
||||
| 4 | 설정 prefix 하나(`app.<모듈>`), `StrictSettingsBinder`, 검증은 record compact constructor | Redis만 예외(AGENTS.md 기준 4) |
|
||||
| 4 | 설정 prefix 하나(`app.<모듈>`), `StrictSettingsBinder`, 검증은 record compact constructor | Redis만 예외(아래) |
|
||||
| 5 | 포트 계약 테스트를 fake와 실제 adapter가 모두 통과, 실 벤더(Testcontainers) 1개 이상 | strict lane(08장) |
|
||||
| 6 | README: 제공하는 것, 추가할 한 줄, env 키 | |
|
||||
| 7 | 이 모듈을 아는 곳은 모듈 자신뿐. bootstrap scan·스위치 목록에 등록하지 않는다 | 줄을 지우면 기능이 완전히 사라지는가 |
|
||||
|
||||
7개를 모두 충족해야 "포장 완료"다. 표의 뜻을 풀면 이렇다.
|
||||
|
||||
1. 서비스 코드는 application-core의 포트만 호출한다. 그래서 모듈을 `runtimeOnly`로 받을 수 있다.
|
||||
2. 모듈이 자기 `AutoConfiguration.imports`를 가진다. 모듈이 있으면 켜지고, 필요하면 `enabled` 설정으로 끌 수 있다. 다른 자동 설정에 기대면 순서를 밝힌다(`afterName`).
|
||||
3. 켜면 완전히 동작한다. 문서에 적은 옵션은 전부 실제로 동작하고, 동작하지 않는 옵션은 설정 키 자체를 두지 않는다.
|
||||
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor에서 한다. 예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중 하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/AGENTS.md`.
|
||||
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 adapter가 모두 통과한다. 실제 벤더(Testcontainers)로 도는 테스트가 1개 이상 있다.
|
||||
6. 모듈 README에 세 가지를 적는다: 제공하는 것, 추가할 한 줄, 필요한 env 키.
|
||||
7. 이 모듈을 아는 곳은 모듈 자신뿐이다. bootstrap의 scan 정규식이나 스위치 목록에 등록하지 않고, 한 줄을 지우면 기능이 완전히 사라진다.
|
||||
|
||||
모듈 설정 기본값은 그 모듈의 `src/main/resources/config/module-defaults/<모듈>.yml`에 두고 `adapter:outbound:support`의 `ModuleDefaultsEnvironmentPostProcessor` 하나가 읽는다. 의존성 closure에 support가 없는 leaf(persistence-mongo, graphql)만 자기 EPP가 `config/<이름>.yml`을 읽는다.
|
||||
|
||||
등록할 공용 파일: `src/config/architecture/modules.json`(leaf와 허용 edge), `src/settings.gradle`이 읽는
|
||||
디렉터리 매핑, app-bootstrap의 허용 edge, 새 leaf lockfile. registry가 허용하지 않은 edge는
|
||||
`architectureCheck`(의존 방향)가 막는다.
|
||||
|
||||
@@ -5,8 +5,8 @@
|
||||
## 배치·이름
|
||||
|
||||
- [ ] 배치를 03장 기준표로 정했다(기본: 계층 leaf 안 `<feature>` 패키지).
|
||||
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
|
||||
- [ ] 이름이 `src/application-core/CLAUDE.md` 「Naming convention」을 따른다.
|
||||
- [ ] 패키지 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않고, 업무 코드를 템플릿 패키지에 넣지 않았다.
|
||||
- [ ] 이름이 `src/application-core/AGENTS.md` 「Naming convention」을 따른다.
|
||||
|
||||
## domain
|
||||
|
||||
|
||||
@@ -40,14 +40,15 @@
|
||||
|
||||
| 무엇 | 정본 |
|
||||
| --- | --- |
|
||||
| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.md`) |
|
||||
| 계층 경계·금지 규칙 | `AGENTS.md`와 가장 가까운 `src/**/AGENTS.md` |
|
||||
| 테스트 작성 규칙 | `.claude/rules/java-tests.md` |
|
||||
| leaf 목록·허용 의존 | `src/config/architecture/modules.json` |
|
||||
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/CLAUDE.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
|
||||
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 |
|
||||
| 이름 규칙(유스케이스·포트·command·query) | `src/application-core/AGENTS.md` 「Naming convention」. 기계 검사는 `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java`와 `ApplicationBoundaryArchitectureTest.java` |
|
||||
| 유스케이스 모양·트랜잭션 모양 | `src/application-core/README.md` 「정해진 유스케이스 모양 (Canonical use case shape)」, `src/application-core/AGENTS.md` 「허용하는 트랜잭션 모양 (Allowed transactional shapes)」 |
|
||||
| HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` |
|
||||
| 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` |
|
||||
| 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` |
|
||||
| capability 완료 기준 7개 | `AGENTS.md` 「부가 기능(capability) 모듈 규칙」 |
|
||||
| capability 완료 기준 7개 | [10-capabilities.md](10-capabilities.md) |
|
||||
|
||||
이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 **따른 결과**를 보여 줄 뿐이고,
|
||||
규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(`scripts/feature-scaffold/templates/`)이 규칙과
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
> `modules.json`은 messaging leaf의 `gradle_path`와 허용 의존성을 관리하지만
|
||||
> `runtime_memberships` 필드는 없다. 실제 런타임 편입은 `app-bootstrap`의 Gradle 의존성과 starter /
|
||||
> auto-configuration 경로가 결정한다. 아래 등급은 "무엇이 증명되었는가"를 말하며 런타임 편입 여부와
|
||||
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/CLAUDE.md`가 소유한다.
|
||||
> 같은 축이 아니다. 자세한 composition/cutover 상태는 `src/platforms/messaging/AGENTS.md`가 소유한다.
|
||||
|
||||
## 브로커 등급
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
파생 서비스가 `adapter:outbound:persistence-mongo`를 실제로 쓰려면 **자기 Mongo 어댑터 leaf**를 하나
|
||||
만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository·
|
||||
mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다
|
||||
(`src/adapter/outbound/persistence-mongo/CLAUDE.md` "Forbidden").
|
||||
(`src/adapter/outbound/persistence-mongo/AGENTS.md` "Forbidden").
|
||||
|
||||
전체 흐름:
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `auth_401_error_rate_high` 또는 `jwks_refresh_failure_spike`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `runbook_link`, `dependency_name`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `authz_cross_tenant_violation` 또는 `authz_403_spike`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `principal_id_pseudonymized`, `tenant_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `dependency_error_rate_critical` 또는 `circuit_breaker_open`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `dependency_name`, `dependency_kind`(required|optional), `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `http_5xx_error_rate_critical`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `request_id`, `traceId`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `job_dead_letter`
|
||||
- alert payload 필수 field: `error.code=JOB_DEAD_LETTER`, `job_name`, `correlation_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `executor_rejected`
|
||||
- alert payload 필수 field: `error.code=JOB_EXECUTOR_REJECTED`, `executor_name`, `policy`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `job_timeout`
|
||||
- alert payload 필수 field: `error.code=JOB_TIMEOUT`, `job_name`, `correlation_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `outbox_dead_letter`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `outbox_publish_failed_rate`, `outbox_publisher_lag` 또는 `outbox_retry_long`
|
||||
- alert payload 필수 field: `error.code=OUTBOX_PUBLISH_FAILED`, `error.reason`, `event_type`, `correlation_id`, `runbook_link`
|
||||
|
||||
@@ -12,7 +12,7 @@ status: 초안
|
||||
|
||||
## 1. Trigger
|
||||
|
||||
이 runbook은 다음 alert에서 발동됩니다.
|
||||
이 runbook은 다음 alert가 울리면 쓴다.
|
||||
|
||||
- alert name: `rate_limit_429_high`
|
||||
- alert payload 필수 field: `operation`, `error.code`, `error.category`, `rate_limit_key_type`(ip|principal|tenant), `runbook_link`
|
||||
|
||||
@@ -196,7 +196,7 @@ PERFORMANCE lane은 상한을 매번 단언한다. 측정만 하고 통과하는
|
||||
|
||||
## 9. application-core 포트의 공유 계약 현황 (review 2026-11-01 01-05·TEST-F-1)
|
||||
|
||||
규칙(`AGENTS.md` 테스트 규칙): 포트마다 fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와
|
||||
규칙(`.claude/rules/java-tests.md` 규칙 6): 포트마다 fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와
|
||||
모든 adapter가 같은 추상 계약 테스트(`*Contract`)를 상속한다. 실제 adapter의 계약 테스트는 그
|
||||
adapter leaf의 실 DB·Redis lane에서 돈다. fake가 실제와 다르게 동작하면 유스케이스 테스트가 거짓
|
||||
녹색이 되기 때문이다.
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
# 업그레이드 안내 — 2026-11 Claude Code 작업 환경(하네스)
|
||||
|
||||
- 범위: 지침 파일 배치(leaf 규칙 문서 이름, 루트 `AGENTS.md`·`CLAUDE.md`), `.claude/`의 권한·훅·규칙·스킬·서브에이전트, 예측·실측 장부
|
||||
- 근거: 소유자 결정(2026-11-07), design-docs `harness/01-harness-design.md` 13절, `docs/work/reference/decisions.md` 「지침 배치」
|
||||
|
||||
## 1. 누가 읽나
|
||||
|
||||
이 템플릿을 받아 도메인을 채운 파생 서비스가 읽는다. 코드·설정·빌드의 동작은 바뀌지 않았다. 바뀐 것은 지침 파일의 자리와 Claude Code 세션 설정이다.
|
||||
|
||||
## 2. 바뀐 것과 할 일
|
||||
|
||||
| # | 바뀐 것 | 서비스가 할 일 |
|
||||
| --- | --- | --- |
|
||||
| 1 | leaf·family 지역 규칙 문서가 `src/**/CLAUDE.md`에서 같은 폴더 `src/**/AGENTS.md`로 옮겨 갔다. 그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄이다 | 서비스가 leaf `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 고친 내용을 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 한 줄로 둔다. 서비스가 새로 만든 leaf도 같은 모양으로 둔다. 서비스 문서·테스트가 `src/<leaf>/CLAUDE.md`의 내용을 읽으면 `AGENTS.md`로 바꾼다(`git grep -n 'CLAUDE\.md' -- docs src`) |
|
||||
| 2 | 루트 `AGENTS.md`가 규칙 정본이자 지도(40줄 이하: 비전·HARD-STOP·지도·맡은 일·검증·일하는 방식)가 됐다. 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄이다. 옛 `AGENTS.md`의 절은 옮겨 갔다: 「Gradle 정책 권위」 → `src/build-logic/AGENTS.md`, 「테스트 전략」의 작성 규칙 → `.claude/rules/java-tests.md`(계층별 기준은 각 계층 `AGENTS.md` 「테스트」), 「모듈 책임」 → `src/adapter/inbound/AGENTS.md`·`src/adapter/outbound/AGENTS.md`·각 core `AGENTS.md`, 「부가 기능(capability) 모듈 규칙」 → `docs/manual/10-capabilities.md`, 「설정과 런타임」 → `.claude/rules/settings-and-runtime.md`, 「템플릿 재사용 체크리스트」 → 루트 `README.md` 「새 서비스로 시작하기」. 「Superpowers Workflow」·「강제 수준」·「금지된 지름길」·「작업 보고 규칙」은 HARD-STOP·전역 규칙과 같은 말이라 지웠다 | 서비스가 루트 `AGENTS.md`나 `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 서비스 고유의 줄은 새 `AGENTS.md`의 같은 절(40줄 안)이나 위 새 자리에 옮긴다. 서비스 문서가 옛 절 이름(「Gradle 정책 권위」 등)을 가리키면 새 자리로 바꾼다 |
|
||||
| 3 | `.claude/rules/`(경로별 규칙)를 추적한다. `.gitignore`에 `!.claude/rules/`를 더했다 | 서비스 `.gitignore`가 `.claude/*`를 무시하면 같은 줄을 더한다 |
|
||||
| 4 | `.claude/settings.json`에 repo 훅을 걸었다(본체 `scripts/hooks/hooks.py`, 설명 `scripts/hooks/README.md`): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 권한으로 막는다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 쪽을 합친다. 훅은 `src/config/architecture/modules.json`, `src/gradle/libs.versions.toml`의 `googleJavaFormat`, `applied-migrations.sha256`을 읽으므로 그 경로를 옮긴 서비스는 `hooks.py` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 |
|
||||
| 5 | Agent 도구 금지를 풀었다(`.claude/settings.json`의 `"Agent"` deny 삭제). 결과만 받는 일은 서브에이전트(`.claude/agents/`의 `arch-reviewer`·`verify-api`·`code-simplifier`)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(`docs/work/delegate.md` 4.3절). `.gitignore`에 `!.claude/agents/`를 더했다 | 서비스가 Agent 도구를 계속 막으려면 자기 `.claude/settings.json`에 `"Agent"` deny를 남긴다. `verify-api`는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다 |
|
||||
| 6 | repo 스킬 둘을 더했다: `.claude/skills/new-feature`(새 기능 실행 순서), `.claude/skills/desktop-gates`(Gradle·Docker를 desktop에서 돌리는 순서). 모델이 설명의 발동 조건을 보고 부른다. 설치된 스킬이 없던 `skills-lock.json`을 지웠다. `.gitignore`에 `!.claude/skills/`를 더했다 | `desktop-gates`는 소유자 환경을 가정하므로 서비스 환경에 맞게 고치거나 지운다. 서비스가 `skills-lock.json`을 썼다면 merge에서 삭제 충돌이 난다. 쓰면 남긴다 |
|
||||
| 7 | 예측·실측 장부 `docs/ledger/estimates.jsonl`(형식 `docs/ledger/README.md`)을 두었다. `.gitattributes`가 이 파일에 `merge=union`을 준다 | 서비스는 템플릿의 줄을 지우고 자기 작업의 줄부터 쌓는다. 템플릿 줄은 템플릿 작업의 기록이다 |
|
||||
| 8 | 지역 규칙이 200줄을 넘던 셋(`src/application-core`, `src/adapter/outbound/persistence-jpa`, `src/adapter/inbound/graphql`)의 표와 계약을 같은 폴더 `README.md` 끝 「지역 규칙에서 옮긴 표와 계약」 절로 옮겼다. 템플릿 패키지 목록(「패키지 소유」 표)의 정본도 `src/application-core/README.md`다 | 서비스가 그 절을 고쳤다면 README의 같은 절로 옮긴다. 서비스 문서·테스트가 `src/application-core/AGENTS.md`의 「Package ownership」 표를 읽으면 `README.md`로 바꾼다 |
|
||||
+9
-7
@@ -1,7 +1,7 @@
|
||||
# 작업 매뉴얼
|
||||
|
||||
이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다.
|
||||
읽는 순서는 하나다: 루트 `CLAUDE.md`(지도) → 이 README → 맡은 일의 playbook 하나.
|
||||
읽는 순서는 하나다: 루트 `AGENTS.md`(지도) → 이 README → 맡은 일의 playbook 하나. Claude Code 세션에서는 루트 `CLAUDE.md`가 `AGENTS.md`를 가져온다.
|
||||
규칙의 정본은 `AGENTS.md`와 registry(`src/config/architecture/modules.json`)다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다.
|
||||
|
||||
## 1. 어떤 playbook인가
|
||||
@@ -24,15 +24,15 @@
|
||||
- brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다.
|
||||
- brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
|
||||
- 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다.
|
||||
- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 `docs/web/http-contract.md`, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 보안 정책.
|
||||
- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 `docs/web/http-contract.md`, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 저장소 루트나 `src/` 최상위에 폴더를 새로 만들거나 옮기는 일, 보안 정책.
|
||||
- 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다([research-design.md](research-design.md)). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다.
|
||||
|
||||
## 3. 모든 작업의 공통 단계
|
||||
|
||||
1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다.
|
||||
2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
|
||||
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/CLAUDE.md`를 읽는다.
|
||||
4. 스킬을 고른다. 정본은 `AGENTS.md` 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다.
|
||||
3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다.
|
||||
4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은 `.claude/skills/`다(`new-feature`, `desktop-gates`). 스킬이 서브에이전트에게 파일을 고치게 하라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절).
|
||||
5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
|
||||
6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다.
|
||||
7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
|
||||
@@ -58,6 +58,7 @@
|
||||
- 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
|
||||
- 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다.
|
||||
- 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다. 테스트 수는 성공한 Gradle 로그에 없으니 결과 XML 사본에서 센다([reference/gates.md](reference/gates.md) 4절).
|
||||
- 착수할 때 예측(p30·p50·p80과 근거)을, 끝 보고 직전에 실측을 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다(형식 `docs/ledger/README.md`).
|
||||
- 사고 순서 흔적 칸을 둔다(`conventions/work-thinking-order.md` 3절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다.
|
||||
|
||||
## 7. 필요할 때만 읽는 문서
|
||||
@@ -68,10 +69,11 @@
|
||||
| [reference/review-criteria.md](reference/review-criteria.md) | 결함 정의, 심각도, 증거·통제 수준, 점검 항목, 리뷰 문서 양식 |
|
||||
| [reference/defect-patterns.md](reference/defect-patterns.md) | 반복해서 나온 결함의 모양과 막는 기준 |
|
||||
| [reference/decisions.md](reference/decisions.md) | 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법 |
|
||||
| [reference/terms.md](reference/terms.md) | 영어 그대로 쓰는 말과 정한 표기의 뜻 |
|
||||
| [evidence.md](evidence.md) | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID |
|
||||
|
||||
## 8. 이 폴더를 고칠 때
|
||||
|
||||
- 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 `AGENTS.md`와 `src/**/CLAUDE.md`도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다.
|
||||
- 이 폴더, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 10줄, 폴더 지역 규칙(`src/**/AGENTS.md`) 200줄(넘으면 표·근거를 그 leaf README로), 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
|
||||
- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 새 세션이 처음 읽는 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 규칙·스킬·서브에이전트 문서도 같다. 모듈 README·설계 문서·`docs/reviews/**`는 ID를 둔다.
|
||||
- 이 폴더, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
|
||||
|
||||
+12
-3
@@ -30,6 +30,8 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
|
||||
이 repo에서 더할 것:
|
||||
|
||||
- 착수 보고(이해한 것, 모호한 점과 고른 가정, 예측)는 하위 세션이 공유 노트에 쓰고 기다리지 않는다. 예측과 실측은 그 세션이 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다. 위임 장부 줄은 그 `task`를 가리킨다.
|
||||
|
||||
- brief의 「작업 종류」는 이 repo의 `docs/work/<종류>.md`다. 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 검증 명령은 [reference/gates.md](reference/gates.md)와 빌드 파일에서 실제 태스크 이름을 확인해 쓴다.
|
||||
- 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, `flock /tmp/claude-gates/heavy.lock`, 로그 `~/<작업 이름>-logs/`([operate.md](operate.md) 4.1절). 7절에는 커밋 허용과 자기 브랜치 push 허용을 따로 쓴다.
|
||||
- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸과 「정한 기본값」부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」와 README 남은 항목을 다시 판정시킬지도 적는다.
|
||||
@@ -61,14 +63,14 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
|
||||
| 파일 | 왜 |
|
||||
| --- | --- |
|
||||
| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹친다 |
|
||||
| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹치고, 머리 「커밋:」 줄을 여럿이 고치면 충돌한다. 묶음은 「커밋:」 줄을 고치지 않고 보고에 커밋을 적는다. 총괄이 합칠 때 한 번에 적는다 |
|
||||
| `docs/reviews/<폴더>/README.md` | 처리 표·결정의 답·게이트 기록·남은 것은 총괄이 쓴다. 리뷰어는 자기 라운드 색인 절 하나만 쓴다([improve.md](improve.md) 4.1절 7단계) |
|
||||
| `src/config/architecture/modules.json`, `src/settings.gradle` | registry 하나가 모든 leaf를 정한다 |
|
||||
| `src/gradle/libs.versions.toml`, lockfile | 의존성을 바꾸면 lockfile 전체가 바뀐다 |
|
||||
| `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 |
|
||||
| `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 |
|
||||
| `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 |
|
||||
| `AGENTS.md`, 루트 `CLAUDE.md`, `docs/work/` | 모든 세션이 읽는다 |
|
||||
| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`·`skills/`·`agents/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 |
|
||||
| `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 |
|
||||
|
||||
나눌 때 지킬 것:
|
||||
@@ -78,13 +80,18 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
- 묶음 크기 상한을 지킨다([improve.md](improve.md) 4.4절: 영역 하나, 발견 8건 이하, 확인 리뷰당 추가 1,500줄 이하).
|
||||
- 전 leaf의 import를 바꾸는 묶음은 나머지를 합친 뒤 혼자 마지막에 한다.
|
||||
- 같은 결함을 두 영역이 보면 한 묶음에만 배정한다.
|
||||
- 같은 파일·장치에서 결함이 두 라운드 연속 나오면 다음 묶음은 수정이 아니라 「이 장치가 필요한가, 형식을 좁혀 없앨 수 있나」를 보는 조사([research-design.md](research-design.md))로 맡긴다.
|
||||
- 합칠 때 충돌 해결 밖에서 새로 고칠 것이 생기면 병합 커밋에 넣지 않고 병합 뒤 따로 커밋한다. 병합 커밋에는 충돌 해결만 둔다.
|
||||
- 합칠 때는 하위 브랜치를 모아 [reference/gates.md](reference/gates.md) 3절 묶음을 돌린다. 합치기와 그 게이트도 하위 세션에 맡길 수 있다.
|
||||
|
||||
### 4.3 소유자 환경
|
||||
|
||||
하위 세션을 띄우는 법, 하위 세션 보고가 총괄에게 전달되는 길이, 공유 노트 폴더, 프론트 repo 일의 경로 같은 소유자 환경 규칙은 design-docs `conventions/delegation-loop.md` 11절 한 곳에 있다. 다시 쓰지 않는다. 이 repo에서 더할 것은 둘이다.
|
||||
|
||||
- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 그 세션이 직접 하거나, 이 playbook대로 별도 세션에 맡긴다. 막혔다고 Agent로 우회하지 않는다.
|
||||
- 나누는 기준(소유자 결정 2026-11-07):
|
||||
- 파일을 바꾸는 위임, 소유자가 열어 보고 멈출 수 있어야 하는 일은 하위 세션(이 playbook)이다.
|
||||
- 결과만 받는 일(넓은 검색, 구조 리뷰 `arch-reviewer`, 앱을 띄워 보는 확인 `verify-api`, 단순화 제안 `code-simplifier`)은 서브에이전트(Agent 도구, 정의는 `.claude/agents/`)다. 서브에이전트는 파일을 고치지 않는다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다.
|
||||
- Gradle·Docker는 누가 돌려도 desktop에서다. 서브에이전트 안에서도 소유자 전역 훅이 노트북 실행을 막는다.
|
||||
- 실행 위치(desktop, 공유 잠금, desktop worktree)는 [operate.md](operate.md) 4.1절이다.
|
||||
- 하위 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립 리뷰어 둘은 노트 파일 이름을 서로 다르게 정해 주고, brief에 상대 노트를 읽지 말라고 쓴다.
|
||||
|
||||
@@ -120,3 +127,5 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
- 묶음을 너무 크게 만들어 마감 안에 검증 보고가 오지 않는다. 묶음 크기 상한을 지킨다.
|
||||
- 하위 세션이 적은 태스크 이름을 확인하지 않고 소유자에게 옮긴다.
|
||||
- 같은 범위를 두 리뷰에 따로 맡기고(비교 시험 등) ID를 매길 쪽을 정하지 않아, 같은 ID가 다른 결함을 가리킨다. brief에 ID를 매길 리뷰 하나를 정한다(규칙은 [reference/review-criteria.md](reference/review-criteria.md) 10절 「ID」).
|
||||
- brief에 「다른 PR과 충돌 없음」을 대상 파일 몇 개만 비교해 적는다. 쓰려면 바뀌는 모든 파일을 `git merge-tree --write-tree <base> <브랜치 A> <브랜치 B>`로 본다.
|
||||
- PR을 만들기 전에 그 head 브랜치의 열린·닫힌 PR과 base 상태를 보지 않아, 이미 병합된 커밋으로 PR을 또 만든다. Gitea API(`/api/v1/repos/<owner>/<repo>/pulls?state=all`)로 먼저 본다.
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## 1. 언제 쓰나
|
||||
|
||||
- `docs/work/`, `docs/manual/`, 루트·leaf `CLAUDE.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
|
||||
- `docs/work/`, `docs/manual/`, 루트·leaf `AGENTS.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
|
||||
- 이것은 아니다.
|
||||
- 리뷰 문서 → [improve.md](improve.md)(리뷰 양식은 [reference/review-criteria.md](reference/review-criteria.md) 10절)
|
||||
- 설계서·ADR → [research-design.md](research-design.md)
|
||||
@@ -28,20 +28,26 @@
|
||||
## 4. 절차
|
||||
|
||||
1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다".
|
||||
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `CLAUDE.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
|
||||
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `AGENTS.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
|
||||
3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다.
|
||||
4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다.
|
||||
4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 문체는 「~한다」다. 높임 문장은 `check-docs.py` `style`이 막는다. 용어는 [reference/terms.md](reference/terms.md)의 표기를 쓰고, 새 용어를 정하면 거기에 더한다. 언어 규칙(`docs/README.md` 「문서 수명과 언어」)은 문서(`.md`)에 걸린다. 코드 주석·Javadoc은 그 파일이 쓰는 언어를 따른다.
|
||||
5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다.
|
||||
6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. 걷어낸 문서 묶음(예: `docs/manual/`, 진입 문서)마다 절 하나를 두고, 같은 묶음을 다시 걷어내면 그 절에 표를 더한다. ID가 무엇을 가리키는지는 evidence.md 머리말 「표기」로 찾는다. 번호의 원래 문서가 이 repo에 없으면 그 번호가 가리키는 규칙 이름과 코드 위치를 근거로 적고, 원래 문서가 repo에 없다고 쓴다.
|
||||
7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다.
|
||||
8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다.
|
||||
9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(지도 3절: brief가 먼저다).
|
||||
10. `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다.
|
||||
10. `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다. 어느 문서든 바꿨으면 `python3 scripts/check-docs.py`도 돌린다(언어, 머리 블록, 참조, 복사한 숫자, 문서 지도, 상대 링크, 문체).
|
||||
11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다.
|
||||
12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`.
|
||||
- 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어 `--history`로 돌린다. `docs/reviews/**` 밖 전체(`git ls-files '*.md' ':!docs/reviews'`)에도 돌려 새로 걸린 줄을 모두 읽는다. 검사 대상 파일의 오탐은 패턴을 좁혀 없애고, 대상 밖의 오탐은 보고에 적는다.
|
||||
- 기본 검사를 넓히는 커밋은 그 검사가 새로 잡는 문서를 고친 커밋 뒤에 둔다(또는 같은 커밋). 그래야 어느 커밋에서도 기본 모드가 rc=0이다.
|
||||
13. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
|
||||
13. 파일·폴더를 옮기는 커밋에는 옮긴 경로를 가리키는 참조 수정(문서 링크, 테스트가 읽는 경로)을 같이 넣는다. 그래야 커밋마다 검사가 통과한다. 내용 수정은 다음 커밋으로 나눈다. 같은 이름의 새 파일이 옛 자리에 생기면 git이 이동으로 잡지 못하니 커밋 본문에 옛 이력을 보는 법을 적는다.
|
||||
14. 옮겨 쓰는(번역하는) 문서의 기준:
|
||||
- 코드·다른 문서가 영어 절 제목으로 인용하는 절은 제목을 「한국어 (English)」로 둔다. 그 제목을 글자로 비교하는 테스트가 있으면 같은 변경에서 고친다.
|
||||
- 레지스트리 yaml(`docs/registries/`)은 값 칸·머리 설명·행별 설명 주석을 한국어로 옮긴다. 출처 줄, 인용, 테스트가 글자로 비교하는 줄은 원문으로 둔다.
|
||||
- 머리말(`docs/runbooks/template.md`의 front matter)이 없는 runbook에 머리말을 새로 만들지 않는다. `error_codes`·`severity`를 채우는 것은 새 결정이라 그 runbook을 맡은 작업에서 한다.
|
||||
- 납품 묶음의 해시 목록(`MANIFEST.sha256`)은 납품 당시 바이트의 해시다(`docs/README.md`). 머리 블록을 달거나 번역해 지금 바이트와 맞지 않게 돼도 목록을 고치지 않고, 지금 파일을 맞춰 보는 검사로 쓰지 않는다.
|
||||
15. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
|
||||
|
||||
**playbook을 새로 만들 때의 뼈대** (모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다):
|
||||
|
||||
@@ -52,7 +58,7 @@
|
||||
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
|
||||
- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다.
|
||||
- 정본을 복사한 문장이 없다. 가리키는 줄만 있다.
|
||||
- `docs/work/`·루트 `CLAUDE.md`·`AGENTS.md`·`src/**/CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
|
||||
- `docs/work/`·루트 `AGENTS.md`·`CLAUDE.md`·`src/**/AGENTS.md`·`.claude/` 아래 문서를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다. 어느 문서든 `scripts/check-docs.py`가 rc=0이다.
|
||||
- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그).
|
||||
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
|
||||
|
||||
@@ -74,7 +80,7 @@
|
||||
[README](README.md) 6절에 더해 적는다.
|
||||
|
||||
- 바꾼 문서와 줄 수, 분량 상한 대비.
|
||||
- 검사 결과: `check-work-docs.py`, `check-review-index.py`, 링크 검사, document-contract lane의 rc와 로그 경로.
|
||||
- 검사 결과: `check-work-docs.py`, `check-docs.py`, `check-review-index.py`, 링크 검사, document-contract lane의 rc와 로그 경로.
|
||||
- cold-read 시험이나 자가 점검: 써 본 brief, 막힌 곳, 고친 것.
|
||||
- 정본과 다른 곳을 찾았으면 그 위치.
|
||||
|
||||
|
||||
@@ -377,3 +377,38 @@
|
||||
- 합계: 52건, 34행. 고침 34행(그중 기본값 7행), 고치지 않음 0, 소유자 결정 필요 0.
|
||||
- 소유자 결정(2026-11-07)으로 한 일: 이력 ID 0 규칙을 진입 문서로 넓혔다(10절, 결정 색인 2.1 「이력 ID 0 규칙의 범위」).
|
||||
- 「자주 하는 실수」에 넣은 줄: `improve.md`(탐침의 Error Prone을 기존 줄에 더함).
|
||||
|
||||
## 12. cold-read 시험 3회차 빈틈과 쌓인 매뉴얼 규칙 처리 (2026-11-07)
|
||||
|
||||
하네스 재설계를 적용한 묶음(design-docs `harness/01-harness-design.md`, 소유자 결정 2026-11-07 「매뉴얼 보강은 한 묶음」)에서 함께 넣었다. 원천은 넷이다: cold-read 3회차(수정 세션 넷 `r9-g1`~`r9-g4`의 빈틈 9건), 위임 장부(design-docs `delegation-loop/ledger.jsonl`)의 `"to": "manual"` 줄 중 백엔드 몫, 공유 노트의 매뉴얼 보강 목록, design-docs `repo-structure/01-backend-layout.md` 10·12절·`02-docs.md` 9절·`03-ci.md` 8절.
|
||||
|
||||
- 처리 칸: 고침(고친 곳) / 이미 있음(그 자리) / 고치지 않음(이유). 「고침(기본값)」은 이 묶음이 정하고 결정 색인에 기본값으로 남긴 것이다.
|
||||
- 1·2회차 빈틈(장부 6~22줄)은 9절·11절에서 이미 처리했다. 다시 넣지 않았다.
|
||||
|
||||
| # | 출처 | 빈틈 | 처리 |
|
||||
| --- | --- | --- | --- |
|
||||
| R3-1 | G1-1 | brief가 옮긴 결정 설명과 결정 원문이 다를 때 무엇을 따르나 | 고침 — `reference/decisions.md` 1절 1(원문을 따르고 차이를 보고) |
|
||||
| R3-2 | G1-3 | desktop 잠금을 여러 세션이 기다릴 때 순서와 시간 | 고침 — `reference/gates.md` 4절 「공유 잠금 기다리기」 |
|
||||
| R3-3 | G2-1 | 커밋하는 수정에서 lockfile을 손으로 고쳐도 되나 | 고침 — `reference/gates.md` 2절 탐침 첫 줄(desktop `resolveAndLockAll --write-locks`) |
|
||||
| R3-4 | G2-2 | desktop에서 자기 실행을 멈추는 법(`pkill -f`가 ssh 세션을 끊음) | 고침 — `operate.md` 4.1절 |
|
||||
| R3-5 | G3-1, G3-3 | 절차 문서 결함과 대기 결함의 RED 모양 | 고침 — `improve.md` 4.2절 3 |
|
||||
| R3-6 | G3-2 | 검증 뒤 앞 커밋에 형식 수정을 넣는 법 | 고침 — `operate.md` 4.1절(커밋을 나누기 전에 확인, 편집 훅이 파일마다 맞춤) |
|
||||
| R3-7 | G4-1 | 그 코드를 지키는 lane을 찾는 법 | 고침 — `improve.md` 4.2절 8 |
|
||||
| R3-8 | G4-2 | upgrade 안내 「커밋:」 줄을 여러 묶음이 고칠 때 | 고침 — `delegate.md` 4.2절 표 |
|
||||
| R3-9 | 장부 r9 통합(5건) | OOM 재시작 거짓 통과, 자원 의존 실패의 판정, `--no-build-cache` 차이, zsh 파이프 rc, 처음 켜진 lane의 이전 실패 | 고침 — `reference/gates.md` 6절 표·4절 「원래 있던 실패 가리기」·3절, `operate.md` 4.1절, `reference/gates.md` 3절 (나) 5 |
|
||||
| R3-10 | 장부 t1(5건) | smoke 이미지 재사용, `if` 안 `set -e`, leaf 데이터 폴더, 트리 해시로 커밋에 묶기, 코드 주석 언어 | 고침 — `reference/gates.md` 4절·6절, `new-feature.md` 6절, 이미 있음 — `operate.md` 4.1절 「push 전에 검증하기」, 고침 — `docs-writing.md` 4절 4 |
|
||||
| R3-11 | 장부 d1(5건) | 이동 커밋과 검사, Gradle 밖 검사의 자리, 줄기만 하는 예외 목록, MANIFEST, scripts 시험 위치 | 고침 — `docs-writing.md` 4절 13·14, `reference/gates.md` 7절 1·8, 이미 있음 — `docs/README.md` 「문서 검사」 |
|
||||
| R3-12 | 장부 i1(4건+2) | 병합에서만 생긴 수정, FROZEN 지문, smoke 이미지, 순서 의존 재현, check-docs 줄 누락, lychee·buf·trivy | 고침(기본값) — `delegate.md` 4.2절(병합 커밋에는 충돌 해결만), 이미 있음 — `docs/README.md`, 고침 — `reference/gates.md` 4절 둘, `docs-writing.md` 4절 10·5절·8절, `review-criteria.md` 9절, `reference/gates.md` 3절 (다) |
|
||||
| R3-13 | 장부 i2(4건) | smoke 이미지 출처, trivy DB 받기, 문체 검사의 주인, 테스트 Javadoc | 고침 — `reference/gates.md` 4절, 고침(기본값) — `operate.md` 4.1절·결정 색인 「desktop 도구 설치」, 고침 — `check-docs.py` `style`, `improve.md` 4.2절 6 |
|
||||
| R3-14 | 장부 d2a, d2c(4건) | 레지스트리 yaml 번역, 영어 절 제목 인용, 머리말 없는 runbook, `@DisplayName` 범위 | 고침 — `docs-writing.md` 4절 14, `.claude/rules/java-tests.md` 규칙 2 |
|
||||
| R3-15 | 장부 41(프론트 총괄) | brief의 「충돌 없음」, 중복 PR | 고침 — `delegate.md` 9절 |
|
||||
| R3-16 | 공유 노트 | 결정 기록 머리 둘째 줄이 번역한 ADR에 맞지 않음 | 고침 — `check-docs.py` `DECISION_LABEL`, `docs/README.md`, ADR 머리 블록. design-docs `docs-system.md` 4.1절과 프론트는 이 repo 밖 |
|
||||
| R3-17 | 공유 노트 | `check-repo-layout.py` 설명과 지도 범위, `template-vs-consumer.md` 분류 | 고침 — 루트 `AGENTS.md` 지도, `check-repo-layout.py`, `docs/ci-cd/template-vs-consumer.md` |
|
||||
| R3-18 | 01-backend-layout 10.1·10.3 | 리뷰 기준의 최상위 폴더·참조 0 파일·배포·개발자 경험·삭제 가능성, 최상위 폴더 일의 크기, 테스트 환경 위치 | 고침 — `review-criteria.md` 관점 2·9·18·20·27, `README.md` 2절, `new-feature.md` 6절 |
|
||||
| R3-19 | 01-backend-layout 12절 | 개발 환경의 뜻 | 고침 — `reference/terms.md`(새) |
|
||||
| R3-20 | 02-docs 9절 | 용어집, 모듈 README 칸, 리뷰의 문서 기준, Important 예시 | 고침 — `reference/terms.md`, `docs/README.md` 「모듈 README」, `review-criteria.md` 관점 4·9·20·23·26·3절 |
|
||||
| R3-21 | 03-ci 8절 | workflow·스크립트를 더하는 기준, 빌드·CI 비례성, 같은 장치 결함 되풀이, runner 사실 | 고침 — `reference/gates.md` 7절, `review-criteria.md` 관점 4·20·21, `improve.md` 7절·`delegate.md` 4.2절, `operate.md` 4.1절 |
|
||||
| R3-22 | 장부 1·33·43줄, 01 10.2·12절 6, 02·03의 design-docs 몫 | 결정 질문 상자, 훅 빈틈, live 클러스터 적용, 성숙도 리뷰 가이드, design-docs README | 고치지 않음 — design-docs(총괄) 몫. 이 repo 밖 |
|
||||
|
||||
- 합계: 22행. 고침 21행(그중 기본값 2), 고치지 않음 1행(이 repo 밖).
|
||||
- 「자주 하는 실수」에 넣은 줄: `delegate.md` 둘.
|
||||
|
||||
@@ -58,18 +58,18 @@
|
||||
1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다.
|
||||
2. RED: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지가 그 결함을 말해야 한다. 컴파일 오류나 준비 실패는 RED가 아니다.
|
||||
3. 수정과 테스트를 이미 같이 썼으면, 기준 커밋에 테스트만 얹은 임시 worktree에서 RED를 본다. 실 DB·Redis가 필요한 결함은 실 vendor lane에서 본다. RED용 임시 파일은 테스트든 main 리소스(임시 마이그레이션 등)든 그 worktree에만 둔다.
|
||||
- RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다.
|
||||
- RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 절차 문서(runbook)의 결함이면 기준 문서의 단계를 그대로 따르는 임시 테스트를 기준 커밋에 얹어 실패를 보이고, 최종 테스트는 새 단계를 따르게 한다. 한 단계가 다른 단계를 기다려 막히는 결함은 시간 제한으로 끊는 도우미로 "기다렸다"를 실행으로 보인다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다.
|
||||
4. 가장 작은 수정으로 GREEN을 본다.
|
||||
5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다. 찾은 자리가 brief 영역 안이고 공개 동작이 바뀌지 않으면 함께 고치고 보고에 적는다. 공개 동작이 바뀌거나 brief 영역 밖이면 고치지 않고 「범위 밖에서 본 것」에 권하는 안과 함께 적는다. 묶음 상한(4.4절)도 지킨다.
|
||||
6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`CLAUDE.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다.
|
||||
6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`AGENTS.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다. 넘겨받은 발견이 테스트 Javadoc·주석이어도 고친다(동작이 바뀌지 않으면 "RED 없음 — 이유").
|
||||
7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 적고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. 문서에 이미 적힌 규칙을 검사가 더 엄하게 지키게 되어 그 규칙을 어기던 코드가 새로 실패하는 것도 여기에 든다(규칙은 이미 정해져 있어 크기는 올리지 않는다).
|
||||
- 안내의 범위(머리 「범위」)가 아직 main에 합쳐지지 않았으면 파생 서비스는 그 행을 받기 전이다. 같은 표면의 행이 있으면 그 행을 고쳐 최종 동작을 적고, 머리 「커밋:」 목록에 이번 커밋을 더한다. main에 합쳐진 안내는 고치지 않고 새 행을 더한다.
|
||||
8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)).
|
||||
8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)). registry는 lane을 모른다. 그 lane은 바꾼 클래스·기능 이름으로 leaf `build.gradle`의 `strictTestLanes` 블록과 lane source set(`src/<lane>/`)의 테스트를 grep해 찾는다. brief의 lane 목록에 없는 lane이 걸리면 그것도 돌리고 보고에 적는다.
|
||||
|
||||
### 4.3 리팩터링, 성능, 구조, 테스트 구조
|
||||
|
||||
- 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다.
|
||||
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `CLAUDE.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
|
||||
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `AGENTS.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
|
||||
- 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.md 「성능 측정」, 지난 기준선은 [evidence.md](evidence.md)다. 지난 숫자는 현재 커밋에서 다시 잰다.
|
||||
- 구조 변경: 설계서(`docs/design/`)와 계획서(`docs/history/plans/`)를 먼저 둔다. review-criteria.md 「leaf 변경 체크리스트」를 따른다. ArchUnit 규칙을 바꾸면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다.
|
||||
- 테스트 구조: 지금 테스트가 증명하는 것(이름, 단언, skip 수)을 적는다. 고친 뒤 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지(변이) 본다. 옮겼으면 lane별 테스트 수를 전후로 비교한다.
|
||||
@@ -102,7 +102,7 @@
|
||||
- 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과).
|
||||
- 구조 변경: `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`가 통과한다. 문서에 leaf 개수를 적지 않았다.
|
||||
- 테스트 구조: 변이가 잡혔다. 새 lane이 단계에 속한다. `testQualityCheck`가 통과한다.
|
||||
- `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
|
||||
- `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
|
||||
|
||||
## 6. 하지 말 것
|
||||
|
||||
@@ -118,6 +118,7 @@
|
||||
|
||||
- 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다. 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이라 묻지 않는다(4.2절 7단계의 안내 행은 적는다). 약속한 곳끼리 다르면 셋째 줄대로 한다.
|
||||
- RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다.
|
||||
- 같은 파일·장치에서 결함이 두 라운드 연속 나오면 그 다음은 수정이 아니라 [research-design.md](research-design.md)로 "이 장치가 필요한가, 형식을 좁혀 없앨 수 있나"를 먼저 본다.
|
||||
- 계약을 적은 곳끼리(설계서, 포트 Javadoc, 모듈 README, 테스트) 다르게 말하고 [reference/decisions.md](reference/decisions.md)에 결정이 없으면, 어느 쪽도 고르지 않는다. 양쪽 근거를 표로 붙이고 권하는 안과 함께 묻는다. 그 발견만 멈춘다.
|
||||
|
||||
## 8. 보고 형식
|
||||
|
||||
@@ -24,13 +24,13 @@
|
||||
- 업무 기능 하나는 보통 중간이다: 계층 leaf 여러 곳에 파일이 생기지만 판단은 매뉴얼이 정해 둔 범위 안이다.
|
||||
- 큼: 새 capability 모듈, 새 leaf, 새 공개 계약, 파생 서비스가 따라 고쳐야 하는 변경. 큰 일은 설계와 소유자 검토가 먼저다([research-design.md](research-design.md)).
|
||||
- 선행 사례는 생성 명령의 출력 하나다. 개별 기법의 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)로 가리킨다.
|
||||
- 스킬: 설계가 바뀌면 `superpowers:brainstorming`, 여러 단계면 `superpowers:writing-plans`, 구현은 `superpowers:test-driven-development`.
|
||||
- 스킬: 이 repo의 `new-feature`(이 playbook의 실행 순서표), 설계가 바뀌면 `superpowers:brainstorming`, 여러 단계면 `superpowers:writing-plans`, 구현은 `superpowers:test-driven-development`.
|
||||
|
||||
## 4. 절차
|
||||
|
||||
1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다.
|
||||
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않는지 본다.
|
||||
3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다.
|
||||
2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `<feature>` 패키지다. 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다.
|
||||
3. capability 모듈이면 `docs/manual/10-capabilities.md`의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다.
|
||||
4. 뼈대를 만든다: `scripts/new-feature.sh <FeatureName>`(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」).
|
||||
5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다.
|
||||
6. 기능에 필요한 장만 더 읽는다: 저장(04), 재시도될 쓰기(05), 오류(06), 권한(07), 테스트 배치(08), 이벤트(09).
|
||||
@@ -56,6 +56,7 @@
|
||||
- 저장 adapter를 `persistence-jpa` leaf 안에 만들지 않는다. 서비스 전용 persistence leaf에 둔다.
|
||||
- 한 단계가 다른 leaf나 계층을 고쳐야 하면 범위를 조용히 넓히지 않는다. 거기서 멈추고 설계를 다시 본다(7절).
|
||||
- bootstrap에 capability 이름·스위치 목록·scan 정규식을 넣지 않는다. 모듈이 자기 `AutoConfiguration.imports`로 켜진다.
|
||||
- 새 capability가 테스트 환경(compose, 스크립트)을 더하면 그 leaf 안에 둔다. 저장소 루트에 두지 않는다. leaf가 가진 기능 데이터(readiness card, release registry)는 그 leaf의 `release/`에 둔다.
|
||||
- 노트북에서 Gradle을 돌리지 않는다.
|
||||
|
||||
## 7. 막혔을 때
|
||||
|
||||
@@ -28,10 +28,12 @@
|
||||
|
||||
> 이 절은 이 repo 소유자의 기계에 묶인 규칙이다. 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다. 다른 환경(파생 서비스 등)은 이 절만 자기 환경으로 바꾼다.
|
||||
|
||||
- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.**
|
||||
- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** 예외는 편집 훅의 한 파일 포매터 하나다(Gradle 없이 JVM 한 번, 캐시에 있는 jar만. 소유자 결정 2026-11-07, `scripts/hooks/README.md`).
|
||||
- desktop의 Gradle·Docker 실행은 모두 공유 잠금 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 짝 프론트 repo도 같은 desktop에서 같은 잠금을 쓴다.
|
||||
- desktop의 기존 checkout `~/workspace/clean-architecture-backend-template`은 여러 세션이 함께 쓴다. 그 `stash@{0}`는 소유자의 보관분이다. 건드리지 않는다. `git stash pop`·`drop`·`clear`와 이름 없는 `git stash`를 쓰지 않는다.
|
||||
- design-docs repo는 노트북 `~/workspace/desktop-server-git/design-docs`에 있다.
|
||||
- desktop 기본 셸은 zsh다. 파이프의 rc는 `bash -o pipefail -c '<명령> | tee <로그>'; echo "rc=$?"`로 받는다(zsh에는 `PIPESTATUS`가 없다). 자기 실행을 멈출 때는 시작할 때 남긴 PID로 `kill <PID>`를 쓴다. `pkill -f <경로>`는 그 경로가 든 ssh 명령줄 자신과도 맞아 세션을 끊는다.
|
||||
- CI runner(2026-11-07): Gitea Actions가 켜졌고, desktop에 `desktop-runner` 하나(`gitea/runner` dind, `capacity: 1`, label `ubuntu-latest`)가 돈다. desktop은 12코어·31GB다. CI job은 공유 잠금을 쓰지 않으므로, 손으로 돌린 게이트가 느리면 `docker ps`로 runner job이 함께 도는지 본다.
|
||||
|
||||
절차:
|
||||
|
||||
@@ -58,7 +60,7 @@ git worktree remove ~/workspace/<작업 이름>
|
||||
|
||||
- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절).
|
||||
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
|
||||
- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다.
|
||||
- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니다. 받아도 되고, 받은 DB의 갱신 시각을 기록에 적는다.
|
||||
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(dev lane overlay `src/app-bootstrap/compose-lanes/dev.yaml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`compose.yaml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
|
||||
- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.
|
||||
|
||||
@@ -75,7 +77,7 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업
|
||||
|
||||
- 그다음 위 3) 4)대로 돌리고 지운다. 결과를 본문에 적어 커밋한 뒤 `git rev-parse HEAD^{tree}`가 같은 해시인지 본다. 같으면 desktop이 돌린 트리가 그 커밋이다.
|
||||
- RED는 같은 방법으로 테스트 파일만 stage해 보낸다. 한 파일의 일부만 stage하는 법은 design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」이다.
|
||||
- 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다.
|
||||
- 형식은 편집 훅이 파일마다 맞추므로 보통 바뀌는 것이 없다. 그래도 커밋을 나누기 전에 확인한다(나눈 뒤에 고치면 앞 커밋을 다시 만들어야 한다). 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다.
|
||||
|
||||
```bash
|
||||
ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --console=plain'
|
||||
@@ -105,8 +107,8 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree'
|
||||
- 파생 서비스는 이 템플릿을 받아 도메인을 채운 repo다. 템플릿 변경을 두 방식으로 받는다: 기준 커밋을 적은 tracked snapshot에 3-way로 반영하거나(`template.lock.json`), `git merge upstream/main`을 한다.
|
||||
- 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다.
|
||||
- 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다.
|
||||
- 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md` 지도에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다.
|
||||
- `.claude/settings.json`(Agent 도구 금지)은 추적 파일이라 함께 넘어간다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다.
|
||||
- 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다.
|
||||
- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`, `skills/`, `agents/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 `.env` 읽기 차단 같은 권한을 바꾸려면 그 파일을 자기 repo에서 고친다.
|
||||
- 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다.
|
||||
|
||||
## 5. 완료 기준
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
## 1. 결정을 다시 묻지 않는 규칙
|
||||
|
||||
1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 **내용**을 옮겨 적는다.
|
||||
1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 **내용**을 옮겨 적는다. brief가 옮긴 내용과 원문이 다르면 원문을 따르고, 차이를 보고에 적는다(brief가 요약하며 빠뜨린 것일 수 있다).
|
||||
2. 다시 열 수 있는 경우는 셋뿐이다.
|
||||
- 결정의 전제가 코드나 측정으로 틀렸다고 확인됐다.
|
||||
- 두 결정이 서로 충돌한다.
|
||||
@@ -32,13 +32,13 @@
|
||||
|
||||
| 주제 | 결정 | 누가 | 날짜 | 출처 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 |
|
||||
| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「일하는 방식」 |
|
||||
| 커밋 예외 | brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다. main 병합·main 또는 다른 브랜치 push·force push는 하지 않는다 | 소유자(2026-11-06), 커밋과 push를 나눠 읽는 것은 기본값(2026-11-06) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」, `docs/work/README.md` 4절, `docs/work/evidence.md` 9절 |
|
||||
| 리뷰 README 분담 | 리뷰어는 리뷰 폴더 README에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면(독립 리뷰어 둘 포함) 색인 절도 총괄이 쓰고, 리뷰어는 보고의 색인 표를 `check-review-index.py --extra-index`로 대조해 rc=0을 보인다 | 기본값 | 2026-11-06, 2026-11-07 | `docs/work/evidence.md` 9·11절 |
|
||||
| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`. 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 |
|
||||
| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`(2026-11-07부터 `src/**/AGENTS.md`, 루트 `CLAUDE.md`, `.claude/` 아래 문서). 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 |
|
||||
| 커밋 단위 | 커밋 하나에 논리 변경 하나(`conventions/commit-and-pr.md` 3.1절). 수정 묶음은 브랜치 하나이고 결함(또는 같은 원인)마다 커밋을 나눈다. 나눈 커밋마다 그 커밋이 바꾼 leaf `check`를 돌리고, 무거운 묶음은 마지막 트리에서 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 |
|
||||
| 넘어온 「범위 밖」 항목 | 수정 세션의 「범위 밖에서 본 것」은 총괄이 README 남은 항목으로 옮기고(멈춤 기준 4가 센다), 다음 확인 리뷰가 brief를 받아 판정한다. 「정한 기본값」은 처리 표와 이 색인 기본값 행으로 옮긴다 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 |
|
||||
| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/operate.md` 4.1절 |
|
||||
| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니라 받아도 된다(기본값 2026-11-07, 갱신 시각을 기록에 적는다) | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/operate.md` 4.1절 |
|
||||
| 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. Slack 브리핑은 전역 `~/.claude/CLAUDE.md` 규칙이 하위 세션에도 그대로 적용된다. brief 7절에 "Slack 말고"가 있으면 보내지 않는다 | 기본값(전역 규칙의 적용 범위를 적음) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「보고」 |
|
||||
| 커밋 예외(지난 것) | `refactor/review-followup`에 Wave마다 커밋(2026-09-25), 리뷰 수정을 `refactor/maturity-review-2026-11`에 커밋·push(2026-11-03) | 소유자 | 2026-09-25, 2026-11-03 | 결정 1, `1101` 17절 |
|
||||
| 리뷰 발견 처리 | Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복한다 | 소유자 | 2026-11-05 | `1103` 16절 |
|
||||
@@ -47,15 +47,17 @@
|
||||
| 무거운 실행 위치 | 노트북에서 Gradle·Docker를 돌리지 않는다. desktop에서 브랜치를 받아 돌린다 | 소유자 | 2026-11-05 | `1103` 17.1절 |
|
||||
| desktop 공유 잠금 | desktop의 Gradle·Docker 실행은 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 프론트와 부하·포트(4173·4174)가 겹치지 않게 | 총괄 지시 | 2026-11-05 | 2026-11-05 총괄 세션 brief, design-docs `conventions/delegation-loop.md` 11절 |
|
||||
| 세션 분업 | 총괄 세션은 지휘만, 실제 작업은 하위 세션 | 소유자 | 2026-11-05 | design-docs `conventions/delegation-loop.md` 2절 |
|
||||
| 하위 에이전트 | Agent 도구(세션 안의 하위 에이전트)를 쓰지 않는다. 막는 장치는 두 템플릿 repo의 프로젝트 설정(`.claude/settings.json`) | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D5 |
|
||||
| 매뉴얼 체계 | 짧은 지도(`CLAUDE.md`) + 작업 종류별 playbook(`docs/work/`) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작 | 소유자 | 2026-11-06 | 같은 문서 D1, D4 |
|
||||
| 하위 에이전트 | ~~Agent 도구(세션 안의 하위 에이전트)를 쓰지 않는다. 막는 장치는 두 템플릿 repo의 프로젝트 설정(`.claude/settings.json`)~~ → 아래 「서브에이전트와 하위 세션」 행에서 바꿈 | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D5 |
|
||||
| 서브에이전트와 하위 세션 | Agent 금지를 푼다. 결과만 받는 일(검색, 구조 리뷰, 직접 돌려 보는 검증, 코드 단순화 제안)은 서브에이전트(`.claude/agents/`)에 맡기고, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션에 맡긴다. Gradle·Docker는 서브에이전트도 desktop에서만 | 소유자 | 2026-11-07 | design-docs `harness/01-harness-design.md` 13절 Q5 |
|
||||
| 매뉴얼 체계 | ~~짧은 지도(`CLAUDE.md`) + 작업 종류별 playbook(`docs/work/`) + 예외 없는 규칙은 훅·게이트. repo 스킬 없이 시작~~ → 아래 「지침 배치」 행에서 바꿈 | 소유자 | 2026-11-06 | design-docs `delegation-loop/02-design.md` 13절 D1, D4 |
|
||||
| 지침 배치 | 정본은 루트 `AGENTS.md`(40줄 이하: 비전·지도·HARD-STOP), 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄. 폴더 규칙은 그 폴더 `AGENTS.md`(`CLAUDE.md`가 가져옴), 폴더를 가로지르는 파일 종류 규칙은 `.claude/rules/`, 특정 시점 절차는 모델이 부르는 스킬(`.claude/skills/`), 예외 없는 규칙은 훅(편집 직후 넛지, 되돌릴 수 없는 것만 차단)·게이트. 편집 훅은 그 파일 하나만 Gradle 없이 포맷한다 | 소유자 | 2026-11-07 | design-docs `harness/01-harness-design.md` 13절 Q1·Q2·Q3·Q6·Q9 |
|
||||
| 크기별 생략 | 작음·중간·큼으로 사고 순서 단계를 줄인다. 크기는 맡기는 쪽이 정하고 맡은 쪽은 올리기만 한다 | 소유자 | 2026-11-06 | 같은 문서 D2, design-docs `conventions/work-thinking-order.md` |
|
||||
| 매뉴얼 검사 장치 | 이력 ID·분량 검사와 리뷰 색인 검사는 Gradle 밖 `scripts/`(`check-work-docs.py`, `check-review-index.py`) | 소유자 | 2026-11-06 | 같은 문서 D6 |
|
||||
| 규칙 ID | 규칙마다 ID(`R-…`)는 아직 붙이지 않는다. 원장이 생길 때 붙인다 | 소유자 | 2026-11-06 | 같은 문서 D7 |
|
||||
| 옛 개선 매뉴얼 | 브랜치 `claude/improvement-manual-6ae516`은 병합하지 않고 재료로만 쓴다 | 소유자 | 2026-11-06 | 같은 문서 D12 |
|
||||
| 개선 매뉴얼을 먼저(지난 것) | 다음 개선 작업 전에 repo마다 개선 매뉴얼을 만든다 → 2026-11-06 「매뉴얼 체계」로 바뀜 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 brief |
|
||||
| 스킬 | 리뷰·수정에 알맞은 스킬을 쓴다 | 소유자 | 2026-11-05 | `1103` 2절 |
|
||||
| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `AGENTS.md` 테스트 작성 규칙 2 |
|
||||
| `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `.claude/rules/java-tests.md` 규칙 2 |
|
||||
| 학습 문서(지난 것) | 삭제된 코드를 설명하는 학습 문서(지금 `docs/history/study/*.ko.md`, `docs/history/packages/*-superpowers-package/`)는 현재 코드에 맞게 갱신 → 2026-11-07 갱신하지 않고 기록으로 보관(머리 블록만 단다)으로 바뀜 | 소유자 | 2026-09-25 | 결정 6, design-docs `repo-structure/README.md` 3.2절 |
|
||||
| 문서 체계 | 문서를 수명으로 나눈다. 살아 있는 문서는 제자리에 두고 한국어로 옮긴다. 기록은 `docs/history/`, 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`에 둔다. 폴더 이름은 짝 프론트와 같이 쓴다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, 적용은 `docs/README.md` |
|
||||
| 한국어의 범위 | 살아 있는 문서는 본문까지 한국어로 쓴다. 기록 문서는 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달고 본문은 원문 그대로 둔다. 상태는 한국어 고정 어휘다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
|
||||
@@ -74,7 +76,7 @@
|
||||
| --- | --- | --- | --- |
|
||||
| outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 `composition:*` 모듈 | 소유자 | 결정 3 |
|
||||
| 새 leaf | `composition:durable-operation`, `adapter:inbound:messaging` 등록 승인 | 위임 | `1101` 15절 |
|
||||
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`·`grpc:*`)는 복사본을 두고 family `CLAUDE.md`에 이유 | 위임 | `1101` 15절(01-11) |
|
||||
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`·`grpc:*`)는 복사본을 두고 family `AGENTS.md`에 이유 | 위임 | `1101` 15절(01-11) |
|
||||
| caller 트랜잭션 guard | `persistence-notification`·`persistence-fileserver` → `persistence-jpa` edge, `CallerTransaction` 하나 | 소유자 | 결정 33 |
|
||||
| id 포트 | notification·fileserver id 포트를 domain `IdFactory`로 옮기지 않음(보류) | 소유자 | 결정 34 |
|
||||
| 소비자 없는 필드 | principal tenant, GraphQL Spring Security resolver, 가명화 키 분리는 하지 않음(보류) | 소유자 | 결정 35 |
|
||||
@@ -170,7 +172,7 @@
|
||||
| 개발 compose Redis | lane Redis에 ACL 계정, "기동 WARN 없음" 검사 유지 | 위임 | `1101` 15절(r3-J) |
|
||||
| 서블릿 오류 디스패치 | 보안 체인이 ERROR 디스패치만 허용 | 기본값 | `1103` 6절 r4-b, 8절 |
|
||||
| 설정 prefix | `app.*`로 통일, `APP_*` env 키 유지 | 소유자 | 결정 16 |
|
||||
| Redis prefix 예외 | `app.redis.*`·`app.capabilities.*`·`app.rate-limit.*` 세 트리 유지, 네 번째 금지 | 위임 | `1101` 15절(05-18), `AGENTS.md` capability 기준 4 |
|
||||
| Redis prefix 예외 | `app.redis.*`·`app.capabilities.*`·`app.rate-limit.*` 세 트리 유지, 네 번째 금지 | 위임 | `1101` 15절(05-18), `docs/manual/10-capabilities.md` 기준 4 |
|
||||
| 로그 설정 | logback이 `app.logging.*`을 읽음, `APP_CACHE_REDIS_TTL_JITTER` deprecated | 위임 | `1101` 15절(07) |
|
||||
| 빈 env 값 | 선택 숫자 설정의 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 | 위임 | `1101` 15절 |
|
||||
| `APP_FLYWAY_ENABLED` | dev·prod에도 적용 | 위임 | `1101` 15절(r3-F) |
|
||||
@@ -193,8 +195,8 @@
|
||||
| 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 |
|
||||
| lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) |
|
||||
| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② |
|
||||
| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `AGENTS.md` 「Gradle 정책 권위」 |
|
||||
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `AGENTS.md` 「Gradle 정책 권위」 |
|
||||
| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `src/build-logic/AGENTS.md` 「lane 캐시와 성능 lane」 |
|
||||
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `src/build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」 |
|
||||
| MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) |
|
||||
| Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | `1101` 15절(09-11) |
|
||||
| httpclient reactive | 삭제 | 소유자 | 결정 9 |
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다.
|
||||
|
||||
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/CLAUDE.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
|
||||
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 의존 방향)와 family·leaf의 책임·금지 절을 담은 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
|
||||
|
||||
## 패턴
|
||||
|
||||
@@ -45,7 +45,7 @@
|
||||
|
||||
- **모양**: 이름이 말한 성질을 단언하지 않는다. 지키려는 코드를 지워도 통과한다. 시간 제한 대기의 결과를 버린다. 계약 케이스를 skip한다.
|
||||
- **막는 기준**: [review-criteria.md](review-criteria.md) 7절 점검표. 변이로 확인한다. skip은 0이거나 설계 이유를 적는다.
|
||||
- **장치**: 포트당 fake와 공유 계약 상속(`AGENTS.md` 테스트 작성 규칙 6), `rejectSkipped`.
|
||||
- **장치**: 포트당 fake와 공유 계약 상속(`.claude/rules/java-tests.md` 규칙 6), `rejectSkipped`.
|
||||
|
||||
### A7. 거짓 통과 게이트
|
||||
|
||||
@@ -121,7 +121,7 @@
|
||||
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc |
|
||||
| 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) |
|
||||
| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) |
|
||||
| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/platforms/messaging/CLAUDE.md`) |
|
||||
| 복사본을 남긴 이유 | 가까운 `AGENTS.md`(예: `src/platforms/messaging/AGENTS.md`) |
|
||||
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` |
|
||||
|
||||
## 패턴을 더하는 법
|
||||
|
||||
@@ -48,9 +48,9 @@
|
||||
| env 키 | `:app-bootstrap:verifyEnvKeys` |
|
||||
| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` |
|
||||
| 의존성 | `verifyDependencyLocks` |
|
||||
| 문서(`docs/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` |
|
||||
| 문서(`docs/**`, `AGENTS.md`·`CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) + `python3 scripts/check-docs.py` |
|
||||
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) |
|
||||
| `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md` | `python3 scripts/check-work-docs.py` |
|
||||
| `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` |
|
||||
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
|
||||
| build-logic·workflow | `-p build-logic check javadoc`, 두 빌드의 `verifyStrictLaneStages --dry-run` |
|
||||
| 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) |
|
||||
@@ -66,15 +66,16 @@
|
||||
|
||||
- 탐침마다 무엇을 단언했는지 적는다. 결함 동작을 단언했으면 rc=0이 확인이고, 약속(Javadoc·결정)을 단언했으면 실패가 확인이다. 둘이 섞이면 rc만으로 결과를 읽을 수 없다.
|
||||
- strict lane에 `--tests`를 붙여 탐침만 돌려도 된다. 단 `requires`(클래스 이름)로 고르는 lane은 고른 클래스가 모두 돌지 않으면 실패한다(`StrictTestLanePlugin`의 required 검사). 그 lane은 필터 없이 돌린다. 필터 실행은 탐침의 증거일 뿐 lane 통과의 증거가 아니다.
|
||||
- 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew <gradle-path>:resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다.
|
||||
- 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다.
|
||||
|
||||
**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 루트 `CLAUDE.md`는 그 범위 밖이라 `scripts/check-work-docs.py`가 본다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다):
|
||||
**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 그 범위 밖의 지침 문서(루트 `AGENTS.md`·`CLAUDE.md`, 지역 규칙 `src/**/AGENTS.md`, `.claude/` 아래 문서)의 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 본다. `src/**/CLAUDE.md`는 `@AGENTS.md` 한 줄이라 링크가 없다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다):
|
||||
|
||||
```bash
|
||||
python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/CLAUDE.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md')
|
||||
python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/AGENTS.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md')
|
||||
```
|
||||
|
||||
`--links docs`만 돌리면 `src/**/README.md`·`src/**/CLAUDE.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다).
|
||||
`--links docs`만 돌리면 `src/**/README.md`·`src/**/AGENTS.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다).
|
||||
|
||||
## 3. 라운드 끝 — 합친 트리의 전체 묶음
|
||||
|
||||
@@ -90,7 +91,7 @@ python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(
|
||||
|
||||
- 태그 두 줄(`releaseCheck`)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·gRPC·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.
|
||||
|
||||
**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
|
||||
**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. workflow 명령에 그 옵션이 없어도(예: `tasks --group verification`) 증거 실행에는 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
|
||||
|
||||
- `mainCheck` 안의 `verifyFeatureScaffold`는 생성한 복사본에서 Gradle을 따로 띄워(`scripts/verify-feature-scaffold.sh`) 바깥의 `--no-build-cache`를 받지 않는다. 바깥 빌드는 FROM-CACHE를 만들 수 없으니 그 로그에 나온 FROM-CACHE는 중첩 빌드의 것이다. 「실제 실행」 칸에 "바깥 FROM-CACHE 0, 중첩 빌드 FROM-CACHE N(태스크 이름)"으로 적는다.
|
||||
|
||||
@@ -133,15 +134,16 @@ bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lan
|
||||
- `pr-adapters.yml`의 `changes` job에 있는 `emit` 줄. lane(web·websocket·httpclient·jpa)마다 정규식이고, `grep -E`로 맞춘다.
|
||||
3. 걸린 workflow·job의 `run` 줄을 그대로 돌린다. matrix가 있으면 값마다 한 번이다(예: jpa는 PostgreSQL 버전마다, httpclient는 transport마다). compose가 필요한 job은 그 job의 `docker compose … up`·`down` 단계도 같이 한다.
|
||||
4. 걸리지 않은 workflow는 이름과 "경로 안 걸림"을, nightly·수동 전용 job은 "PR·main 단계 아님"을 결과 표에 적는다.
|
||||
5. 경로로 처음 켜진 lane이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 lane이 켜짐), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 lane 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다.
|
||||
|
||||
(다) 로컬에 도구가 없는 것:
|
||||
|
||||
| job | 로컬에서 | 대체가 못 보는 것 |
|
||||
| --- | --- | --- |
|
||||
| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사 | 외부 URL |
|
||||
| `ci-quality-gates.yml` `grpc-proto-buf`(`buf lint`·`buf breaking`) | buf가 있으면 job의 `run` 줄 그대로. 없으면 못 돌림으로 적는다. diff에 `.proto`·`buf*.yaml`이 없으면 "해당 없음 — proto 변경 없음" | 전부 |
|
||||
| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL |
|
||||
| `ci-quality-gates.yml` `grpc-proto-buf`(`buf lint`·`buf breaking`) | buf나 desktop에 이미 있는 buf 공식 이미지가 있으면 job의 `run` 줄 그대로. 없으면 못 돌림으로 적는다. diff에 `.proto`·`buf*.yaml`이 없으면 "해당 없음 — proto 변경 없음" | 전부 |
|
||||
| `dependency-vulnerability.yml` `dependency-review`·`dependency-submission` | GitHub에서만 돈다. diff에 lockfile·`src/gradle/libs.versions.toml` 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 | 전부 |
|
||||
| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy가 있으면 job의 검사 줄 그대로. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) |
|
||||
| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 job의 검사 줄 그대로. workflow가 쓰는 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) |
|
||||
|
||||
## 4. 결과 기록
|
||||
|
||||
@@ -166,6 +168,12 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
|
||||
- 같은 트리 해시에서 돈 자기 실행 로그가 있다(맡은 발견이 이미 커밋된 수정에 들어 있을 때 등). 로그에 적힌 트리 해시와 지금 트리 해시를 함께 적는다.
|
||||
- 트리가 다르거나 다른 세션 보고의 「통과」는 증거가 아니다(E0). 다시 돌린다.
|
||||
|
||||
**smoke 이미지가 이 트리에서 만들어졌음을 보이기.** smoke·compose lane은 Docker 레이어 캐시를 쓴다. 이미지 생성 시각은 runtime 레이어가 캐시에서 오면 증거가 못 된다. 앱 jar를 복사하는 단계가 smoke 로그의 build 출력에서 `CACHED`가 아닌지 본다. 앱 jar가 이 트리에서 새로 만들어졌으면 그 단계는 캐시가 될 수 없다. 결과 표 「실제 실행」 칸에 그 줄과 이미지 id를 적는다.
|
||||
|
||||
**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수를 적는다.
|
||||
|
||||
**공유 잠금 기다리기.** 순서는 `flock`이 정한다(먼저 잡은 쪽). 따로 순번을 정하지 않는다. 기다리는 명령은 background로 두고 다른 일을 하며, 대기는 완료나 첫 실패에서 끝나는 것 하나로 둔다. 30분 넘게 못 잡으면 `ps -o pid,etime,args -C flock`으로 쥔 쪽을 보고 맡긴 쪽에 알린다([operate.md](../operate.md) 7절).
|
||||
|
||||
함께 적는다:
|
||||
|
||||
- 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다.
|
||||
@@ -177,7 +185,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
|
||||
|
||||
## 5. 성능 lane
|
||||
|
||||
- performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `AGENTS.md` 「Gradle 정책 권위」와 `docs/testing/TESTING_STRATEGY.md`의 PERFORMANCE 문단이다.
|
||||
- performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `src/build-logic/AGENTS.md` 「lane 캐시와 성능 lane」과 `docs/testing/TESTING_STRATEGY.md`의 PERFORMANCE 문단이다.
|
||||
- strict lane convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣는다. leaf나 lane은 이 값을 선언하지 않는다.
|
||||
- 빌드(`-P`, `GRADLE_OPTS`)나 lane이 `true` 아닌 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다. `-Pperformance.assertions.enabled=true`는 받지만 줄 필요가 없다.
|
||||
- 그래서 desktop에서 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
|
||||
@@ -199,12 +207,28 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
|
||||
| --- | --- |
|
||||
| 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) |
|
||||
| optional 빌드를 보지 않음 | optional 빌드도 같은 검사 |
|
||||
| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `AGENTS.md` 「Gradle 정책 권위」의 세는 규칙 |
|
||||
| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `src/build-logic/AGENTS.md` 「`verifyStrictLaneStages`가 세는 명령」 |
|
||||
| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 |
|
||||
| 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) |
|
||||
| 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 |
|
||||
| 시간 단언을 끈 채 performance lane 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) |
|
||||
| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다. 집계 태스크는 새 worktree와 `--no-build-cache`로 돌리고 FROM-CACHE 0을 보인다(3절) |
|
||||
| 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` |
|
||||
| smoke rc=0인데 앱이 OOM으로 재시작함 | `scripts/run-compose-runtime-smoke.sh`가 lane 컨테이너 재시작·OOMKilled를 실패로 보고 `restarts.txt`·`app-memory-peak-bytes.txt`를 남긴다. 그 밖의 compose 실행은 `docker inspect -f '{{.RestartCount}} {{.State.OOMKilled}}' <컨테이너>`로 본다 |
|
||||
| 셸 함수·`if` 조건 안에서 `set -e`가 꺼져 중간 실패가 지나감 | 실패를 받아야 하는 명령은 `if`·`&&`·`||` 조건 밖에 두거나 rc를 직접 본다(`<명령>; rc=$?; [ "$rc" -eq 0 ] \|\| exit "$rc"`) |
|
||||
|
||||
게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.
|
||||
|
||||
## 7. workflow·검사 스크립트를 더할 때
|
||||
|
||||
리뷰는 빠진 검사만 찾기 쉽다. 장치를 더하기 전에 아래를 보고, 더하는 PR 본문에 답을 적는다. workflow 파일을 고치는 일은 CI 담당 작업이 한다.
|
||||
|
||||
1. 어느 단계인가(PR·main·nightly·release), 그리고 그 단계의 기존 workflow에 job으로 넣을 수 없는 이유를 한 줄로 쓴다. 모듈 이름의 workflow 파일은 만들지 않는다.
|
||||
2. 새 job이 다른 단계가 이미 돌리는 태스크를 다시 돌리지 않는지 `--dry-run` 태스크 목록으로 보인다.
|
||||
3. lane 고르기·순서·집계는 Gradle에 둔다. 단계 job의 `run:`은 한 줄이다.
|
||||
4. 경로 필터를 새로 쓰려면 그 lane이 다른 단계에서 무조건 돈다는 것을 보인다.
|
||||
5. 문서·이름·개수·CI 배선을 검사하는 것은 main 단계다(2026-09-16 소유자 결정). PR에 두어야 하면 이유를 적는다.
|
||||
6. 이벤트별 job 수 변화와 잰 실행 시간을 적는다. runner 용량은 [operate.md](../operate.md) 4.1절의 값으로 판단한다.
|
||||
7. 실행 환경(Gitea)에서 돌지 않는 action·권한(`id-token`, ghcr, GitHub 의존성 그래프, `upload-artifact@v4` 이상)을 쓰지 않는다. 써야 하면 `github.server_url` 조건을 단다.
|
||||
8. Gradle 밖 검사 스크립트는 `scripts/`에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 `scripts/tests/`에 unittest로 둔다. `docs-check.yml`이 PR마다 `python3 -m unittest discover -s scripts/tests`로 돌린다.
|
||||
9. 같은 장치에서 결함이 두 라운드 연속 나오면 고치기 전에 그 장치가 필요한지 다시 본다([improve.md](../improve.md) 7절).
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
| 등급 | 정의 |
|
||||
| --- | --- |
|
||||
| Critical | 전체 리뷰의 Critical과 같다 |
|
||||
| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자에게 틀린 조치를 시키는 문서 |
|
||||
| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자·개발자에게 틀린 조치를 시키는 문서(예: README·`AGENTS.md`가 지운 타입을 지금 것으로 설명, 지운 설정 키를 켜라고 함) |
|
||||
| Minor | 그 밖의 결함. 예: 거짓 실패 쪽 검사, 좁은 조건의 불일치, 문구 |
|
||||
|
||||
확인 리뷰 발견에는 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. 이번 수정이 만든 것은 회귀로 따로 센다.
|
||||
@@ -70,7 +70,7 @@
|
||||
|
||||
| 수준 | 이 repo의 증거 | 주장할 수 없는 것 |
|
||||
| --- | --- | --- |
|
||||
| E0 설명·주장 | README, `CLAUDE.md`, Javadoc, 리뷰 문서의 이전 실행 기록, 묶음 보고의 "통과" | 현재 커밋의 동작 |
|
||||
| E0 설명·주장 | README, `AGENTS.md`·`CLAUDE.md`, Javadoc, 리뷰 문서의 이전 실행 기록, 묶음 보고의 "통과" | 현재 커밋의 동작 |
|
||||
| E1 정적 확인 | 현재 커밋의 코드·설정·`build.gradle`·workflow를 `file:line`으로 읽음, `--dry-run` 그래프 | 실행 결과 |
|
||||
| E2 테스트 실행 | 이름을 댄 테스트, leaf `check`, `ci`가 현재 커밋에서 통과(명령, rc, 테스트 수) | 실 vendor, 부하, 장애 |
|
||||
| E3 통합·실험 | Testcontainers 실 PostgreSQL·Redis·Kafka·MinIO lane, `java -jar`·compose 실제 기동, 부하·장애 주입·동시 요청 실험 | 운영 환경, 운영 기간 |
|
||||
@@ -101,14 +101,14 @@
|
||||
| # | 관점 | 볼 곳 | 이런 증거면 결함 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 |
|
||||
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
|
||||
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md`, 저장소 루트와 `src/`의 최상위 목록(폴더마다 계층·조립 leaf, Gradle 루트 표준 `build-logic`·`gradle`·`config`, 지도에 적힌 예외 `platforms/`, 저장소 운영 `docs`·`scripts`·`.github` 중 하나인지) | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import, 역할을 한 문장으로 말할 수 없는 최상위 폴더, 같은 역할의 폴더가 같은 높이에 여럿, 지도(`AGENTS.md`)와 `scripts/check-repo-layout.py` 허용 목록에 없는 최상위 항목 |
|
||||
| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 |
|
||||
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 |
|
||||
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수, 루트 README만 읽고 구조·매뉴얼·첫 실행을 5분 안에 찾는가(cold-read 결과), 이벤트별 workflow job 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음, 같은 Gradle 태스크를 두 단계 이상이 돎(의도한 행렬 제외) |
|
||||
| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 |
|
||||
| 6 | 실패 성숙도 | 예외 분류, `retryable`, 결과 불명 | 결과 불명을 확실함으로, 재시도 가능을 확정 실패로 기록 |
|
||||
| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/registries/metrics.yaml`, 종료 순서 | runbook이 틀린 조치를 시킴, 레지스트리 지표를 아무 코드도 내보내지 않음 |
|
||||
| 8 | 디버깅 가능성 | `ServerFailureLog`, correlation id, 오류 코드 | 서버 실패를 남기지 않음, 원인이 다른 실패를 같은 코드로 |
|
||||
| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석 | 갈라진 복사본, 현재 동작과 다른 주석·문서 |
|
||||
| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석, 살아 있는 문서의 표본 주장(문서 종류마다 1~2개 파일, 파일마다 주장 2~5개를 코드와 대조하고 틀린 비율을 README에 적는다), 기록 문서의 상태 칸 | 갈라진 복사본, 현재 동작과 다른 주석·문서, 코드·테스트·workflow·스크립트 어디서도 읽지 않는 비소스 파일(compose, 셸 스크립트, 설정, README. 파일마다 `git grep -l -F <경로> -- ':!docs/history' ':!docs/reviews'`가 0건. 경로를 변수로 조립하는 workflow `matrix`는 따로 본다) |
|
||||
| 10 | 테스트 성숙도 | 7절 | 이름의 성질을 단언하지 않음, 변이 생존, 계약 밖 fake |
|
||||
| 11 | 데이터 성숙도 | 마이그레이션 스트림, 유일 제약, `@Version`, 잠금 시간 제한 | 중복 규칙에 DB 제약 없음, 적용된 마이그레이션 수정, `lock_timeout` 없는 강한 잠금 |
|
||||
| 12 | 동시성 성숙도 | claim·lease, `SKIP LOCKED`, 트랜잭션 경계 | 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim |
|
||||
@@ -117,16 +117,16 @@
|
||||
| 15 | 보안 성숙도 | 인증·인가 체인, `docs/security/public-paths-snapshot.txt`, `docs/registries/secrets-classification.yaml`, 로그 | 기본으로 꺼진 검증, 권한 검사 없는 경로, 로그로 새는 입력값 |
|
||||
| 16 | 의존성 성숙도 | `src/gradle/libs.versions.toml`, lockfile, `src/config/testing/container-images.properties` | 사라진 외부 이미지, 운영 jar의 테스트용 드라이버 |
|
||||
| 17 | API·계약 성숙도 | `docs/web/http-contract.md`, `docs/registries/error-codes.yaml`, `docs/architecture/*-api-surface.txt`, 짝 프론트 계약 | 코드·문서·짝 계약이 서로 다름 |
|
||||
| 18 | 배포 성숙도 | `src/Dockerfile`, compose, `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서 |
|
||||
| 18 | 배포 성숙도 | 저장소 루트 `compose.yaml`, `src/Dockerfile`, 테스트 lane 계약(`compose-profile-contracts.json`), `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서, README의 개발 환경 기동 명령이 실제로 뜨지 않음, 개발 환경을 띄우는 길이 둘 이상, 개발 환경 compose와 테스트 fixture가 한 파일에 섞임, Kubernetes 매니페스트·프록시 설정·IaC가 이 repo에 있음(배포 경계 `docs/ci-cd/boundary.md`) |
|
||||
| 19 | 설정 성숙도 | `StrictSettingsBinder`, `docs/registries/env-keys.yaml`, `config/module-defaults/<모듈>.yml`, `verifyEnvKeys` | 바인딩되지만 동작하지 않는 키, 한 설정을 두 곳에서 읽음 |
|
||||
| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함 |
|
||||
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 |
|
||||
| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간, 빈 clone에서 README 명령만으로 개발 환경을 띄우고 내리기(compose 파일 하나), 문서 지도가 모든 문서 폴더를 덮는가(`check-docs.py` `map`), 템플릿 CI 변경이 파생 서비스 동기화에서 건드리는 파일 수 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함, 개발 환경에 compose 파일이 둘 이상 필요함 |
|
||||
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계, 편집 훅(`scripts/hooks/`), CI 실행 기록(URL) | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사, CI 최근 실행 기록이 없음(확인 못 하면 「미검증」이 아니라 결함 후보), 검사 장치가 지키는 대상보다 큼, 같은 장치에서 두 라운드 연속 결함, 개수·문서·배선 검사가 PR 단계에 있음, 실행 환경(Gitea)에서 돌지 않는 action·권한 |
|
||||
| 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 |
|
||||
| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 |
|
||||
| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
|
||||
| 23 | 일관성 | 같은 역할의 이름·모양·규칙, 문서의 언어·문체·상태 어휘(`check-docs.py` `language`·`style`·`head`) | 같은 개념이 여러 벌, 한 문서 안에서 문체가 섞임 |
|
||||
| 24 | 네이밍·의미 | `src/application-core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
|
||||
| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 |
|
||||
| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
|
||||
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 |
|
||||
| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README(자기 것이나 family 것) | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
|
||||
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거, 샘플·예시 모듈 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎, 매뉴얼·생성 명령이 같은 역할을 하는데 남은 샘플(그 샘플이 어떤 게이트의 유일한 검증 대상이면 그 역할과 옮길 곳이 적혀 있는지) |
|
||||
| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 |
|
||||
|
||||
**따라갈 시나리오** (가이드 31절). 전체 리뷰는 시나리오마다 요청 하나를 끝까지 따라가며 입력 신뢰 수준, 권한 판단 위치, 규칙 소유자, 트랜잭션 시작과 끝, 외부 부작용, 오류 변환을 적는다. 해당 기능이 없으면 적용 제외 사유를 한 줄 적는다.
|
||||
@@ -147,7 +147,7 @@
|
||||
|
||||
## 7. 테스트가 증명해야 하는 것
|
||||
|
||||
정본: 테스트 작성 규칙은 `AGENTS.md` 「테스트 전략」, 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`(기계 기준 `TestLaneCategory`), 새 기능의 테스트 배치는 `docs/manual/08-testing.md`다.
|
||||
정본: 테스트 작성 규칙은 `.claude/rules/java-tests.md`, 계층별 검증 기준은 그 계층의 `AGENTS.md` 「테스트」 절, 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`(기계 기준 `TestLaneCategory`), 새 기능의 테스트 배치는 `docs/manual/08-testing.md`다.
|
||||
|
||||
| 점검 | 결함 모양 |
|
||||
| --- | --- |
|
||||
@@ -199,9 +199,9 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신
|
||||
- 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다.
|
||||
- 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다.
|
||||
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
|
||||
- 템플릿 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
- 템플릿 패키지 목록은 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
|
||||
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
|
||||
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
|
||||
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
|
||||
- 마이그레이션은 저장소마다 자기 디렉터리와 history table을 가진다. 번호는 스트림 안의 순번이다. 어딘가에 적용된 파일은 고치지 않는다(`src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`이 해시를 고정한다).
|
||||
- 문서 위치 규칙은 `docs/README.md`가 정본이다.
|
||||
@@ -212,11 +212,12 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
|
||||
- [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나
|
||||
- [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다)
|
||||
- [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports`
|
||||
- [ ] leaf `CLAUDE.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
|
||||
- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표
|
||||
- [ ] leaf `AGENTS.md`(그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄), 자기 README나 family README의 다섯 칸(`docs/README.md` 「모듈 README」). capability면 README에 제공하는 것, 추가할 한 줄, 필요한 env 키
|
||||
- [ ] 템플릿 패키지를 더하거나 지우면 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표와 `TemplatePackageOwnership`
|
||||
- [ ] ArchUnit 규칙과 그 위반·허용 fixture
|
||||
- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다)
|
||||
- [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행
|
||||
- [ ] 문서를 바꿨으면 `python3 scripts/check-docs.py`와 `python3 scripts/check-work-docs.py`
|
||||
|
||||
검증은 [gates.md](gates.md) 2절의 "leaf 경계·의존·registry" 행이다.
|
||||
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
# 용어
|
||||
|
||||
이 repo가 영어 그대로 쓰는 말과, 한국어로 정한 말의 뜻이다. 문서는 처음 나올 때 이 표기를 쓴다. 용어 순서(자연스러운 한국어 → 한국어(영어) → 영어 그대로)의 정본은 design-docs `conventions/docs-system.md` 3절이다.
|
||||
|
||||
| 표기 | 뜻 |
|
||||
| --- | --- |
|
||||
| leaf | registry(`src/config/architecture/modules.json`)에 등록된 Gradle 프로젝트 하나. 경계의 단위다 |
|
||||
| family | 이름 앞부분이 같은 leaf 묶음(`adapter:inbound:*`, `messaging:*`). 공통 규칙은 그 폴더의 `AGENTS.md`다 |
|
||||
| registry | leaf 목록·경로·허용 의존의 정본 파일 `src/config/architecture/modules.json` |
|
||||
| capability | `runtimeOnly` 한 줄로 켜고 끄는 부가 기능 모듈(`docs/manual/10-capabilities.md`) |
|
||||
| 조립(composition) | 기능을 엮기만 하는 leaf(`src/composition/*`)나 `app-bootstrap`의 배선 |
|
||||
| lane | 같은 조건(실 DB, 컨테이너, 시간)으로 묶어 돌리는 테스트 실행 단위. strict lane은 build-logic `strictTestLanes`가 정의한 것 |
|
||||
| 단계 | workflow가 게이트를 도는 때: PR, main, nightly, 태그 |
|
||||
| 개발 환경 | 루트 `compose.yaml` 하나로 띄우는 로컬 스택(앱 컨테이너의 Spring 프로필은 `local`). `src/app-bootstrap/compose-lanes/`의 overlay는 테스트 lane fixture다. 그중 `dev.yaml`·`prod-smoke.yaml`은 앱을 Spring 프로필 `dev`·`prod`로 띄워 그 프로필의 기동을 보는 lane이고, 개발 환경이 아니다 |
|
||||
| 게이트 | 통과해야 병합·릴리스하는 검사(`docs/work/reference/gates.md`) |
|
||||
| outbox | 트랜잭션 안에 남긴 이벤트를 relay가 나중에 발행하는 방식 |
|
||||
| HARD-STOP | 어기면 동작해도 완료가 아닌 일곱 조건(루트 `AGENTS.md`) |
|
||||
| brief | 다른 세션에 일을 맡기는 지시문(`docs/work/delegate.md`) |
|
||||
| 총괄 | 일을 나누고 brief를 쓰고 결과를 대조하는 세션 |
|
||||
| 하위 세션 | 총괄이 띄운 별도 세션. 파일을 바꾸는 위임을 맡는다. 소유자가 열어 보고 멈출 수 있다 |
|
||||
| 서브에이전트 | 한 세션 안에서 Agent 도구로 띄우는 도우미(`.claude/agents/`). 결과만 돌려준다 |
|
||||
| 훅, 넛지 | 훅은 Claude Code가 정해진 때 대신 돌리는 명령(`scripts/hooks/`). 넛지는 막지 않고 알리기만 하는 훅이다 |
|
||||
| 탐침 | 의심 결함을 보려고 버릴 worktree에서 잠깐 돌리는 테스트(`docs/work/reference/gates.md` 2절) |
|
||||
| RED, GREEN | 수정 전 실패를 실행으로 본 것, 수정 뒤 통과를 본 것 |
|
||||
| 살아 있는 문서, 기록 | 코드와 같이 고치는 문서, 쓴 때의 글로 두고 머리 블록만 고치는 문서(`docs/README.md`) |
|
||||
@@ -26,7 +26,7 @@
|
||||
- `docs/reviews/`의 리뷰 README 「결정」 절과 영역 문서의 「Declined to judge」
|
||||
- `docs/adr/`(되돌리기 비싼 선택), `docs/design/`(설계서), `docs/history/plans/`(계획서)
|
||||
- `git log --oneline -- <경로>`와 커밋 본문의 "고른 방법과 버린 대안"
|
||||
- 가장 가까운 `src/**/CLAUDE.md`와 모듈 README
|
||||
- 가장 가까운 `src/**/AGENTS.md`와 모듈 README
|
||||
- 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(Spring Boot, Flyway, Hibernate 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다.
|
||||
- 스킬: `superpowers:brainstorming`, 결정 기록은 `documentation-and-adrs`, 공식 문서 확인은 `source-driven-development`. 큰 판단은 `doubt-driven-development`로 반론을 세운다.
|
||||
|
||||
|
||||
+94
-4
@@ -43,7 +43,7 @@
|
||||
python3 scripts/check-docs.py --only head # 하나만 (language, head, reference, number, map, readme)
|
||||
python3 -m unittest discover -s scripts/tests # 이 검사의 시험
|
||||
|
||||
Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(AGENTS.md 「Gradle 정책 권위」).
|
||||
Gradle 밖에 둔다. 빌드는 문서를 파싱하지 않는다(src/build-logic/AGENTS.md 「저장소 파일을 읽는 테스트」).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -61,7 +61,7 @@ from pathlib import Path
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
EXCEPTIONS_FILE = "scripts/check-docs-exceptions.txt"
|
||||
REGISTRY_FILE = "src/config/architecture/modules.json"
|
||||
CHECKS = ("language", "head", "reference", "number", "map", "readme")
|
||||
CHECKS = ("language", "head", "reference", "number", "map", "readme", "link", "style")
|
||||
|
||||
# 기록: 본문은 쓴 때의 원문이다. 머리 블록만 고친다. 종류는 폴더가 정한다.
|
||||
RECORD_KINDS = [
|
||||
@@ -91,7 +91,7 @@ STATUS = {
|
||||
HEAD_START = "<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->"
|
||||
HEAD_END = "<!-- 머리 블록 끝 -->"
|
||||
RECORD_LABEL = "> **기록 · {kind}** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다."
|
||||
DECISION_LABEL = "> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다."
|
||||
DECISION_LABEL = "> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다."
|
||||
HEAD_FIELDS = ("상태", "작성일", "요약", "현재 정본")
|
||||
HEAD_OPTIONAL = ("대체", "대체됨")
|
||||
HEAD_SEARCH_LINES = 20
|
||||
@@ -148,6 +148,13 @@ VERSION = re.compile(r"(?<![\w.§])v?\d+\.\d+\.\d+(?:[.-][A-Za-z][A-Za-z0-9]*)*(
|
||||
SPRING_BOOT_CELL = re.compile(r"^Spring Boot(?:\s+(?:BOM|버전))?$")
|
||||
CELL_MARKUP = re.compile(r"[*_`]")
|
||||
LINK_TEXT = re.compile(r"\[([^\]\n]*)\]\([^)\s]*\)")
|
||||
# 상대 링크: 살아 있는 문서의 `[글](경로)`가 이 트리의 파일·폴더를 가리킨다. lychee(link-check.yml)는 PR에서
|
||||
# 정해진 경로만 보고, 그 밖의 문서(`src/**/AGENTS.md`, `.claude/**`, 루트 `AGENTS.md`)의 상대 링크는 이 검사만 본다.
|
||||
LINK_TARGET = re.compile(r"\[[^\]\n]*\]\(([^)\s]+)\)")
|
||||
URL_SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*:", re.I)
|
||||
# 문체: 살아 있는 문서는 「~한다」로 쓴다(docs/README.md 「문서 수명과 언어」). 높임 문장 끝을 잡는다.
|
||||
CORNER_QUOTED = re.compile(r"「[^」\n]*」")
|
||||
POLITE = re.compile(r"(?:습니다|합니다|입니다|됩니다|십시오|하세요|주세요)(?=[.!?)\]」\s]|$)")
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -367,6 +374,88 @@ def inline_spans(lines: list[str]) -> list[tuple[int, str]]:
|
||||
return spans
|
||||
|
||||
|
||||
def link_targets(lines: list[str]) -> list[tuple[int, str]]:
|
||||
"""(줄 번호, 상대 링크 대상) — 코드 블록·인라인 코드·「이력」 인용 블록 밖에서만."""
|
||||
targets, fence, history = [], None, False
|
||||
for number, line in enumerate(lines, start=1):
|
||||
match = FENCE.match(line)
|
||||
if fence:
|
||||
if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence):
|
||||
fence = None
|
||||
continue
|
||||
if match:
|
||||
fence = match.group(1)
|
||||
continue
|
||||
quoted = line.lstrip().startswith(">")
|
||||
if quoted and HISTORY_QUOTE.match(line):
|
||||
history = True
|
||||
elif not quoted:
|
||||
history = False
|
||||
if history:
|
||||
continue
|
||||
for found in LINK_TARGET.finditer(INLINE.sub("", line)):
|
||||
target = found.group(1).split("#", 1)[0]
|
||||
if target and not URL_SCHEME.match(target):
|
||||
targets.append((number, target))
|
||||
return targets
|
||||
|
||||
|
||||
def check_link(root: Path, files: list[str]) -> list[Problem]:
|
||||
known = known_paths(root)
|
||||
problems = []
|
||||
for path in files:
|
||||
if not is_living(path):
|
||||
continue
|
||||
text = (root / path).read_text(encoding="utf-8")
|
||||
lines = body_lines(text)
|
||||
offset = len(text.split("\n")) - len(lines)
|
||||
for number, target in link_targets(lines):
|
||||
resolved = posixpath.normpath(posixpath.join(posixpath.dirname(path), target))
|
||||
if resolved.startswith("..") or not is_known(known, resolved):
|
||||
problems.append(Problem("link", path, target, f"없는 곳을 가리키는 상대 링크다: {target}",
|
||||
number + offset))
|
||||
return problems
|
||||
|
||||
|
||||
def prose_lines(lines: list[str]) -> list[tuple[int, str]]:
|
||||
"""(줄 번호, 인라인 코드를 뺀 줄) — 코드 블록과 「이력」 인용 블록 밖에서만."""
|
||||
kept, fence, history = [], None, False
|
||||
for number, line in enumerate(lines, start=1):
|
||||
match = FENCE.match(line)
|
||||
if fence:
|
||||
if match and match.group(1)[0] == fence[0] and len(match.group(1)) >= len(fence):
|
||||
fence = None
|
||||
continue
|
||||
if match:
|
||||
fence = match.group(1)
|
||||
continue
|
||||
quoted = line.lstrip().startswith(">")
|
||||
if quoted and HISTORY_QUOTE.match(line):
|
||||
history = True
|
||||
elif not quoted:
|
||||
history = False
|
||||
if not history:
|
||||
kept.append((number, INLINE.sub("", line)))
|
||||
return kept
|
||||
|
||||
|
||||
def check_style(root: Path, files: list[str]) -> list[Problem]:
|
||||
problems = []
|
||||
for path in files:
|
||||
if not is_living(path):
|
||||
continue
|
||||
text = (root / path).read_text(encoding="utf-8")
|
||||
lines = body_lines(text)
|
||||
offset = len(text.split("\n")) - len(lines)
|
||||
for number, line in prose_lines(lines):
|
||||
# 「~합니다」처럼 낫표나 따옴표 안의 말은 이 문서의 문장이 아니라 인용이다.
|
||||
found = POLITE.search(CORNER_QUOTED.sub("", QUOTED.sub("", line)))
|
||||
if found:
|
||||
problems.append(Problem("style", path, line.strip()[:80], f"높임 문체다(「~한다」로 쓴다): …{found.group(0)}",
|
||||
number + offset))
|
||||
return problems
|
||||
|
||||
|
||||
def registry_projects(root: Path) -> set[str]:
|
||||
registry = root / REGISTRY_FILE
|
||||
if not registry.is_file():
|
||||
@@ -634,7 +723,8 @@ def check_readme(root: Path, files: list[str]) -> list[Problem]:
|
||||
|
||||
|
||||
RUNNERS = {"language": check_language, "head": check_head, "reference": check_reference, "number": check_number,
|
||||
"map": check_map, "readme": check_readme}
|
||||
"map": check_map, "readme": check_readme, "link": check_link,
|
||||
"style": check_style}
|
||||
|
||||
|
||||
def read_exceptions(text: str) -> list[str]:
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
추적 파일만 본다(git ls-files). build 출력과 IDE 폴더는 처음부터 대상이 아니다.
|
||||
|
||||
새 최상위 항목이 정말 필요하면 아래 목록과 루트 CLAUDE.md 5절 「최상위 폴더는 정해진 것만 둔다」를 같은
|
||||
새 최상위 항목이 정말 필요하면 아래 목록과 루트 AGENTS.md 「지도」의 최상위 줄을 같은
|
||||
변경에서 고친다. 최상위 폴더를 만들거나 옮기는 일은 파일 하나여도 큰 일이다(docs/work/README.md 2절).
|
||||
|
||||
Gradle 밖에 둔다: 빌드는 저장소 배치를 판단하지 않는다(scripts/check-work-docs.py와 같은 자리).
|
||||
@@ -38,7 +38,7 @@ REGISTRY = "src/config/architecture/modules.json"
|
||||
# 저장소 루트: 문서·스크립트·CI·개발 환경과 Gradle 루트(src)뿐이다.
|
||||
ROOT_ALLOWED = {
|
||||
# 폴더
|
||||
".claude": "에이전트 세션 설정(추적되는 settings.json)",
|
||||
".claude": "Claude Code 세션 설정(추적: settings.json의 권한·훅, rules·skills·agents)",
|
||||
".github": "workflow와 공용 action",
|
||||
"compose": "compose.yaml이 마운트하는 보조 파일",
|
||||
"docs": "문서",
|
||||
@@ -50,12 +50,11 @@ ROOT_ALLOWED = {
|
||||
".lycheeignore": "링크 검사(lychee)가 건너뛸 URL. lychee는 저장소 루트의 이 이름만 읽는다",
|
||||
".tool-versions": "JDK 버전 고정",
|
||||
".trivyignore.yaml": "취약점 검사 예외",
|
||||
"AGENTS.md": "규칙 정본",
|
||||
"CLAUDE.md": "작업 지도",
|
||||
"AGENTS.md": "규칙 정본이자 작업 지도",
|
||||
"CLAUDE.md": "Claude Code 진입점(AGENTS.md를 가져온다)",
|
||||
"README.md": "저장소 소개",
|
||||
"compose.yaml": "개발 환경(하나뿐)",
|
||||
"renovate.json": "의존성 갱신 봇 설정",
|
||||
"skills-lock.json": "에이전트 스킬 고정",
|
||||
"testcontainers.properties.example": "Testcontainers 로컬 설정 예",
|
||||
}
|
||||
|
||||
@@ -195,8 +194,8 @@ def main() -> int:
|
||||
print(f"FAIL: {failure}", file=sys.stderr)
|
||||
print(
|
||||
"check-repo-layout: a new top-level entry changes the repository's shape. If it is "
|
||||
"wanted, add it to the allow list in scripts/check-repo-layout.py and to CLAUDE.md "
|
||||
"section 5 in the same change.",
|
||||
"wanted, add it to the allow list in scripts/check-repo-layout.py and to the map in "
|
||||
"AGENTS.md in the same change.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
|
||||
+78
-22
@@ -1,21 +1,26 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Fail when the work manual stops being readable without history or grows past its size limits.
|
||||
|
||||
The work manual is the root `CLAUDE.md` (the map) plus `docs/work/`. A session that has never seen
|
||||
this repository's history reads the map, `docs/work/README.md` and one playbook, and must be able
|
||||
to finish the job from those alone. Two things break that, and both are mechanical:
|
||||
The work manual is the root `AGENTS.md` (the map and the rule book) plus `docs/work/`. A Claude Code
|
||||
session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and adds a few
|
||||
Claude-only lines. A session that has never seen this repository's history reads the map,
|
||||
`docs/work/README.md` and one playbook, and must be able to finish the job from those alone. Two
|
||||
things break that, and both are mechanical:
|
||||
|
||||
1. History IDs in the body. A sentence such as "fixed as in 1101/05-01" means nothing to a reader
|
||||
who does not know that review. History belongs in `docs/work/evidence.md`, and the two reference
|
||||
files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`).
|
||||
The same rule covers the other files a new session reads first: the rule book `AGENTS.md` and
|
||||
every `src/**/CLAUDE.md` (owner decision 2026-11-07). Module READMEs, design documents and
|
||||
`docs/reviews/**` keep their IDs, because a reader can follow them from inside the repository.
|
||||
2. Length. Each entry file has a line limit, and the entry path (map + README + one playbook) has a
|
||||
total limit, so a session reads the whole path instead of skimming it.
|
||||
The same rule covers the other files a new session reads first: the root `AGENTS.md` and
|
||||
`CLAUDE.md`, and every folder rule book `src/**/AGENTS.md` (owner decision 2026-11-07). Module
|
||||
READMEs, design documents and `docs/reviews/**` keep their IDs, because a reader can follow them
|
||||
from inside the repository.
|
||||
2. Length. Each entry file has a line limit (a folder rule book src/**/AGENTS.md too: 200), and the entry path (map + root `CLAUDE.md` + README +
|
||||
one playbook) has a total limit, so a session reads the whole path instead of skimming it. The
|
||||
map limit is 40 lines (owner decision 2026-11-07: vision, map and HARD-STOP only).
|
||||
|
||||
It also checks that every playbook keeps the shared nine-section skeleton, that the
|
||||
"common mistakes" section stays short, and that relative links in the checked files resolve.
|
||||
"common mistakes" section stays short, that every folder rule book src/**/AGENTS.md has a CLAUDE.md
|
||||
beside it that only imports it, and that relative links in the checked files resolve.
|
||||
|
||||
This lives outside Gradle on purpose: the build does not parse documents.
|
||||
|
||||
@@ -34,8 +39,10 @@ import sys
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
MAP = REPO_ROOT / "CLAUDE.md"
|
||||
RULE_BOOK = REPO_ROOT / "AGENTS.md"
|
||||
MAP = REPO_ROOT / "AGENTS.md"
|
||||
CLAUDE_ENTRY = REPO_ROOT / "CLAUDE.md"
|
||||
IMPORT_LINE = "@AGENTS.md"
|
||||
CLAUDE_FOLDERS = ("rules", "skills", "agents")
|
||||
WORK = REPO_ROOT / "docs/work"
|
||||
README = WORK / "README.md"
|
||||
|
||||
@@ -58,7 +65,11 @@ EVIDENCE = "evidence.md"
|
||||
# Files that may name history, relative to docs/work/. Everything else must not.
|
||||
HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-patterns.md"}
|
||||
|
||||
MAP_LIMIT = 120
|
||||
MAP_LIMIT = 40
|
||||
CLAUDE_ENTRY_LIMIT = 10
|
||||
# A folder rule book is read whole whenever a file in that folder is opened. Claude Code's guidance is
|
||||
# under 200 lines per instruction file; tables and design reasons go to the leaf README.
|
||||
MODULE_GUIDE_LIMIT = 200
|
||||
README_LIMIT = 80
|
||||
PLAYBOOK_LIMIT = 150
|
||||
ENTRY_PATH_LIMIT = 350
|
||||
@@ -134,7 +145,7 @@ def line_count(path: Path) -> int:
|
||||
|
||||
|
||||
def check_exists(errors: list[str]) -> bool:
|
||||
expected = [MAP, RULE_BOOK, README, WORK / EVIDENCE]
|
||||
expected = [MAP, CLAUDE_ENTRY, README, WORK / EVIDENCE]
|
||||
expected += [WORK / name for name in PLAYBOOKS + REFERENCES]
|
||||
missing = [rel(path) for path in expected if not path.is_file()]
|
||||
for name in missing:
|
||||
@@ -143,12 +154,12 @@ def check_exists(errors: list[str]) -> bool:
|
||||
|
||||
|
||||
def check_limits(errors: list[str], report: list[str]) -> None:
|
||||
for path, limit in [(MAP, MAP_LIMIT), (README, README_LIMIT)]:
|
||||
for path, limit in [(MAP, MAP_LIMIT), (CLAUDE_ENTRY, CLAUDE_ENTRY_LIMIT), (README, README_LIMIT)]:
|
||||
lines = line_count(path)
|
||||
report.append(f"{rel(path)}: {lines}/{limit}")
|
||||
if lines > limit:
|
||||
errors.append(f"{rel(path)}: {lines} lines, limit {limit}")
|
||||
base = line_count(MAP) + line_count(README)
|
||||
base = line_count(MAP) + line_count(CLAUDE_ENTRY) + line_count(README)
|
||||
for name in PLAYBOOKS:
|
||||
path = WORK / name
|
||||
lines = line_count(path)
|
||||
@@ -158,7 +169,7 @@ def check_limits(errors: list[str], report: list[str]) -> None:
|
||||
errors.append(f"{rel(path)}: {lines} lines, limit {PLAYBOOK_LIMIT}")
|
||||
if entry > ENTRY_PATH_LIMIT:
|
||||
errors.append(
|
||||
f"{rel(path)}: entry path CLAUDE.md + docs/work/README.md + this file is {entry} lines,"
|
||||
f"{rel(path)}: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {entry} lines,"
|
||||
f" limit {ENTRY_PATH_LIMIT}"
|
||||
)
|
||||
|
||||
@@ -195,18 +206,59 @@ def check_skeleton(errors: list[str]) -> None:
|
||||
)
|
||||
|
||||
|
||||
SKIPPED_PARTS = {"build", ".gradle", "node_modules"}
|
||||
|
||||
|
||||
def module_guides() -> list[Path]:
|
||||
"""Every src/**/CLAUDE.md, the local rule book of a leaf or a family, outside build output."""
|
||||
skipped = {"build", ".gradle", "node_modules"}
|
||||
"""Every src/**/AGENTS.md, the local rule book of a leaf or a family, outside build output."""
|
||||
return sorted(
|
||||
path
|
||||
for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
|
||||
if not skipped.intersection(path.relative_to(REPO_ROOT).parts)
|
||||
for path in (REPO_ROOT / "src").rglob("AGENTS.md")
|
||||
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts)
|
||||
)
|
||||
|
||||
|
||||
def check_guide_pairs(errors: list[str]) -> None:
|
||||
"""Every folder rule book src/**/AGENTS.md has a CLAUDE.md beside it that only imports it, so Claude
|
||||
Code reads the same book when it opens a file there. A CLAUDE.md that holds rules is a second book."""
|
||||
for guide in module_guides():
|
||||
if not guide.with_name("CLAUDE.md").is_file():
|
||||
errors.append(f"{rel(guide.with_name('CLAUDE.md'))}: missing; it must be the one line '{IMPORT_LINE}'")
|
||||
for entry in sorted(path for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
|
||||
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts)):
|
||||
lines = [line.strip() for line in entry.read_text(encoding="utf-8").splitlines() if line.strip()]
|
||||
if lines != [IMPORT_LINE]:
|
||||
errors.append(f"{rel(entry)}: must be exactly '{IMPORT_LINE}'; the rules live in AGENTS.md beside it")
|
||||
if not entry.with_name("AGENTS.md").is_file():
|
||||
errors.append(f"{rel(entry)}: imports {rel(entry.with_name('AGENTS.md'))}, which does not exist")
|
||||
|
||||
|
||||
def check_guide_limits(errors: list[str], report: list[str]) -> None:
|
||||
longest = 0
|
||||
for guide in module_guides():
|
||||
lines = line_count(guide)
|
||||
longest = max(longest, lines)
|
||||
if lines > MODULE_GUIDE_LIMIT:
|
||||
errors.append(f"{rel(guide)}: {lines} lines, limit {MODULE_GUIDE_LIMIT}"
|
||||
" (move tables and design reasons to the leaf README and leave a pointer)")
|
||||
report.append(f"longest src/**/AGENTS.md: {longest}/{MODULE_GUIDE_LIMIT}")
|
||||
|
||||
|
||||
def check_claude_entry(errors: list[str]) -> None:
|
||||
"""The root CLAUDE.md starts with the import, so a Claude Code session reads the map."""
|
||||
lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines()
|
||||
if not lines or lines[0].strip() != IMPORT_LINE:
|
||||
errors.append(f"{rel(CLAUDE_ENTRY)}: the first line must be '{IMPORT_LINE}'")
|
||||
|
||||
|
||||
def claude_documents() -> list[Path]:
|
||||
"""The tracked Claude Code documents a session reads: path rules, skills, subagent definitions.
|
||||
Only these folders: the rest of .claude/ is local state (worktrees, settings.local.json)."""
|
||||
return sorted(path for folder in CLAUDE_FOLDERS for path in (REPO_ROOT / ".claude" / folder).rglob("*.md"))
|
||||
|
||||
|
||||
def history_checked_files() -> list[Path]:
|
||||
files = [MAP, RULE_BOOK]
|
||||
files = [MAP, CLAUDE_ENTRY] + claude_documents()
|
||||
for path in sorted(WORK.rglob("*.md")):
|
||||
if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED:
|
||||
files.append(path)
|
||||
@@ -265,7 +317,8 @@ def check_history(errors: list[str], report: list[str]) -> None:
|
||||
|
||||
|
||||
def check_links(errors: list[str], report: list[str]) -> None:
|
||||
checked, broken = broken_links([MAP, RULE_BOOK] + sorted(WORK.rglob("*.md")))
|
||||
checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + module_guides()
|
||||
+ claude_documents())
|
||||
for path, number, target in broken:
|
||||
errors.append(f"{rel(path)}:{number}: broken relative link '{target}'")
|
||||
report.append(f"relative links checked: {checked}")
|
||||
@@ -310,6 +363,9 @@ def main() -> int:
|
||||
report: list[str] = []
|
||||
if check_exists(errors):
|
||||
check_limits(errors, report)
|
||||
check_claude_entry(errors)
|
||||
check_guide_pairs(errors)
|
||||
check_guide_limits(errors, report)
|
||||
check_skeleton(errors)
|
||||
check_history(errors, report)
|
||||
check_links(errors, report)
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# repo 훅
|
||||
|
||||
Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 `.claude/settings.json`, 본체는 `hooks.py` 하나, 시험은 `scripts/tests/test_hooks.py`다. 모델이 잊어도 돈다.
|
||||
|
||||
```text
|
||||
Edit·Write 직전 ──> pre-edit ──> H13 적용된 migration이면 막는다(종료 코드 2)
|
||||
Edit·Write 직후 ──> post-edit ──> Java면 포맷 → N1 레이어 의존 알림, 문서면 N2 문서 검사 알림
|
||||
Bash 직후 ──> post-bash ──> desktop에서 Gradle을 돌렸으면 N5 기록을 비운다
|
||||
턴 끝 ──> stop ──> N5 Java를 고쳤는데 desktop 실행이 없으면 한 번 알린다
|
||||
```
|
||||
|
||||
## 1. 원칙
|
||||
|
||||
- 되돌릴 수 없는 것만 막는다. 나머지는 알리기만 한다(넛지). 알림은 종료 코드 0이고, 모델 컨텍스트에 몇 줄(최대 5줄)만 더한다.
|
||||
- 훅은 게이트의 일부만 본다. 정본은 게이트(desktop `architectureCheck`, `spotlessCheck`, 문서 검사)다. 훅이 틀리면 훅을 고치거나 끄고, 게이트는 그대로 둔다.
|
||||
- 노트북에서 Gradle·Docker를 돌리지 않는다. 포매터는 Gradle 없이 JVM 하나로 파일 하나만 맞춘다(소유자 결정 2026-11-07).
|
||||
- 받거나 설치하지 않는다. 포매터 jar는 Gradle이 이미 캐시에 받아 둔 것만 쓴다. 없으면 건너뛰고 세션에 한 번 알린다.
|
||||
- 표준 라이브러리만 쓴다. 되돌릴 수 없는 명령 차단(force push, 범위 밖 `rm -rf`, DB·볼륨 삭제)과 비밀 값 알림은 repo가 아니라 소유자 전역 훅과 하네스 플러그인 몫이다.
|
||||
|
||||
## 2. 훅마다
|
||||
|
||||
| ID | 때 | 하는 일 | 결과 |
|
||||
| --- | --- | --- | --- |
|
||||
| H13 | PreToolUse `Edit\|Write\|MultiEdit` | `src/**/src/main/resources/db/migration/<키>`의 `<키>`가 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 있으면 막는다 | 종료 코드 2와 「새 버전 파일을 더한다」 안내 |
|
||||
| 포맷 | PostToolUse `Edit\|Write\|MultiEdit` | `src/**/*.java`(build-logic과 `build/` 제외)를 google-java-format으로 맞춘다. 버전은 카탈로그 `googleJavaFormat`, jar는 Gradle 캐시, 옵션은 Spotless 단계와 같게 `--skip-reflowing-long-strings --replace` | 파일이 바뀌면 「다시 읽는다」 한 줄. 문법 오류면 첫 줄들 |
|
||||
| N1 | 같은 때, `src/**/src/main/java/**/*.java` | registry로 그 파일의 leaf를 찾고 import를 본다: 순수성 목록(`DomainPurityArchitectureTest`, `verifyApplicationCoreDependencyPurity`와 같은 패키지), inbound의 persistence 접근, `dev.caskeleton.*`의 주인 leaf가 registry `allowed_dependencies`(전이 포함)에 있는지 | 「HARD-STOP N 의심」 줄 |
|
||||
| N2 | 같은 때, `*.md` | `scripts/check-work-docs.py`와 `scripts/check-docs.py`를 돌린다 | 실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만 |
|
||||
| N5 | Stop | 이 세션에서 Java를 고친 뒤 `ssh <desktop 호스트> … gradlew …` 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 Java 편집 전까지 한 번 |
|
||||
|
||||
- N5가 기억하는 것은 `.claude/hook-state/<session_id>.json`이다(git이 무시한다).
|
||||
- 권한 쪽 차단: `.claude/settings.json`의 `permissions.deny`가 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 막는다. `.env.example` 같은 예시는 막지 않는다.
|
||||
|
||||
## 3. 시험
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
```
|
||||
|
||||
- 고장 낸 입력(적용된 migration 편집, 도메인의 Spring import, 들여쓰기가 틀린 Java, 깨진 링크)에서 막힘·알림이 나오고, 맞는 입력에서 조용한지 본다.
|
||||
- 실제 포매터 시험은 Gradle 캐시에 카탈로그 버전 jar가 있는 기계에서만 돈다. 그 밖에서는 가짜 `java`로 옵션·파일 전달·바뀜 감지를 본다.
|
||||
- 훅을 고치면 조건을 끈 사본에서도 시험이 실패하는지 본다(변이 시험). 조건 하나를 끄는 것마다 시험 하나 이상이 실패해야 한다.
|
||||
|
||||
## 4. 끄기
|
||||
|
||||
훅이 시끄럽거나 틀리면 `.claude/settings.json`에서 그 항목을 지우고, 이유를 커밋 본문에 쓴다. 개인적으로만 끄려면 `.claude/settings.local.json`(git이 무시한다)에 `"disableAllHooks": true`를 둔다.
|
||||
@@ -0,0 +1,461 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Claude Code repo hooks: nudge right after an edit, block only what cannot be undone.
|
||||
|
||||
Called by `.claude/settings.json`, one event per invocation, with the hook input JSON on stdin:
|
||||
|
||||
python3 scripts/hooks/hooks.py pre-edit # PreToolUse Edit|Write|MultiEdit H13
|
||||
python3 scripts/hooks/hooks.py post-edit # PostToolUse Edit|Write|MultiEdit format, N1, N2
|
||||
python3 scripts/hooks/hooks.py post-bash # PostToolUse Bash records desktop Gradle runs
|
||||
python3 scripts/hooks/hooks.py stop # Stop N5
|
||||
|
||||
What each ID does, and why it nudges instead of blocking, is in scripts/hooks/README.md. A nudge
|
||||
exits 0 and adds at most a few lines to the model's context; only H13 exits 2. No hook runs Gradle
|
||||
or Docker: the owner's laptop never does (docs/work/operate.md 4.1). The formatter is one JVM on
|
||||
one file, from the jar Gradle already cached. Standard library only. The tests are
|
||||
scripts/tests/test_hooks.py.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import shlex
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
REGISTRY = "src/config/architecture/modules.json"
|
||||
CATALOG = "src/gradle/libs.versions.toml"
|
||||
MIGRATION_MANIFEST = "src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256"
|
||||
STATE_DIR = ".claude/hook-state"
|
||||
EDIT_TOOLS = ("Edit", "Write", "MultiEdit")
|
||||
MAX_LINES = 5
|
||||
|
||||
# --- formatter: the step Spotless runs (QualityConventionsPlugin), on one file -----------------------
|
||||
GJF_GROUP = "com.google.googlejavaformat/google-java-format"
|
||||
# The Spotless step keeps long strings as written; the CLI reflows them unless told not to.
|
||||
GJF_FLAGS = ("--skip-reflowing-long-strings", "--replace")
|
||||
GJF_EXPORTS = tuple(f"--add-exports=jdk.compiler/com.sun.tools.javac.{part}=ALL-UNNAMED"
|
||||
for part in ("api", "code", "file", "parser", "tree", "util"))
|
||||
GJF_TIMEOUT = 25
|
||||
# Spotless is not applied to build-logic (it is its own build), so the hook leaves it alone too.
|
||||
FORMAT_EXCLUDED = ("src/build-logic/",)
|
||||
SKIPPED = "포맷을 건너뛰었다"
|
||||
|
||||
# --- N1: the layer rules the gates hold, checked on the imports of one edited main source --------------
|
||||
# Mirrors DomainPurityArchitectureTest (DOMAIN_IS_PURE, DOMAIN_HAS_NO_LOGGER).
|
||||
DOMAIN_FORBIDDEN = ("org.springframework.", "jakarta.persistence.", "javax.persistence.", "jakarta.servlet.",
|
||||
"org.hibernate.", "lombok.", "org.slf4j.", "java.util.logging.", "ch.qos.logback.",
|
||||
"org.apache.logging.log4j.")
|
||||
# Mirrors VerifyApplicationCoreDependencyPurityTask and the application-core AGENTS.md forbidden list.
|
||||
APPLICATION_FORBIDDEN = ("org.springframework.", "org.slf4j.", "ch.qos.logback.", "org.apache.logging.log4j.",
|
||||
"io.micrometer.", "java.util.logging.", "jakarta.persistence.", "javax.persistence.",
|
||||
"lombok.")
|
||||
SHARED_FORBIDDEN = ("org.springframework.", "jakarta.", "javax.persistence.", "org.hibernate.", "lombok.")
|
||||
# HARD-STOP 2: an inbound adapter reaching the store.
|
||||
INBOUND_FORBIDDEN = ("org.springframework.data.repository.", "org.springframework.data.jpa.",
|
||||
"org.springframework.data.mongodb.repository.", "jakarta.persistence.", "javax.persistence.")
|
||||
IMPORT = re.compile(r"^\s*import\s+(static\s+)?([\w.]+)(\.\*)?\s*;", re.M)
|
||||
PROJECT_PREFIX = "dev.caskeleton."
|
||||
MAIN_JAVA = re.compile(r"^(?P<leaf>src/.+?)/src/main/java/(?P<rest>.+\.java)$")
|
||||
|
||||
# --- N2: the document checks a living document edit can break -------------------------------------------
|
||||
DOC_CHECKS = (("scripts/check-work-docs.py",), ("scripts/check-docs.py",))
|
||||
DOC_TIMEOUT = 20
|
||||
|
||||
# --- N5: a Bash command that ran Gradle on the desktop clears the pending Java edits --------------------
|
||||
DESKTOP_HOST = re.compile(r"desktop")
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# plumbing
|
||||
|
||||
|
||||
def project_root(payload: dict) -> Path:
|
||||
root = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd()
|
||||
return Path(root).resolve()
|
||||
|
||||
|
||||
def relative(root: Path, file_path: str | None) -> str | None:
|
||||
if not file_path:
|
||||
return None
|
||||
path = Path(file_path)
|
||||
if not path.is_absolute():
|
||||
path = root / path
|
||||
try:
|
||||
return path.resolve().relative_to(root).as_posix()
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
|
||||
def edited_path(payload: dict) -> str | None:
|
||||
if payload.get("tool_name") not in EDIT_TOOLS:
|
||||
return None
|
||||
return relative(project_root(payload), (payload.get("tool_input") or {}).get("file_path"))
|
||||
|
||||
|
||||
def context(event: str, lines: list[str]) -> str:
|
||||
"""The PostToolUse output that adds lines to the model's context without blocking."""
|
||||
text = "\n".join(lines[:MAX_LINES] + ([f"(… {len(lines) - MAX_LINES}줄 더)"] if len(lines) > MAX_LINES else []))
|
||||
return json.dumps({"hookSpecificOutput": {"hookEventName": event, "additionalContext": text}},
|
||||
ensure_ascii=False)
|
||||
|
||||
|
||||
def state_file(root: Path, session_id: str) -> Path:
|
||||
safe = re.sub(r"[^A-Za-z0-9_.-]", "_", session_id or "unknown")
|
||||
return root / STATE_DIR / f"{safe}.json"
|
||||
|
||||
|
||||
def load_state(root: Path, session_id: str) -> dict:
|
||||
try:
|
||||
return json.loads(state_file(root, session_id).read_text(encoding="utf-8"))
|
||||
except (OSError, ValueError):
|
||||
return {"java_edits": [], "reminded": False}
|
||||
|
||||
|
||||
def save_state(root: Path, session_id: str, state: dict) -> None:
|
||||
path = state_file(root, session_id)
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# H13 — an applied migration is never edited
|
||||
|
||||
|
||||
def applied_migrations(root: Path) -> set[str]:
|
||||
try:
|
||||
text = (root / MIGRATION_MANIFEST).read_text(encoding="utf-8")
|
||||
except OSError:
|
||||
return set()
|
||||
return {line.split()[1] for line in text.splitlines() if line.strip() and not line.startswith("#")
|
||||
and len(line.split()) == 2}
|
||||
|
||||
|
||||
def migration_key(path: str) -> str | None:
|
||||
"""`src/<leaf>/src/main/resources/db/migration/jpa/core/V1__x.sql` → `jpa/core/V1__x.sql`."""
|
||||
marker = "/src/main/resources/db/migration/"
|
||||
if marker not in path or not path.endswith(".sql"):
|
||||
return None
|
||||
return path.split(marker, 1)[1]
|
||||
|
||||
|
||||
def h13_message(root: Path, path: str | None) -> str | None:
|
||||
key = migration_key(path) if path else None
|
||||
if key is None or key not in applied_migrations(root):
|
||||
return None
|
||||
return (f"[H13 적용된 migration 편집 금지] {path}\n"
|
||||
"이 파일은 이미 적용된 migration이다(" + MIGRATION_MANIFEST + "에 있다). Flyway가 기동마다 checksum을"
|
||||
" 대조하므로 고치면 운영 DB가 뜨지 않는다.\n"
|
||||
"대신 새 버전 파일(V<다음 번호>__<설명>.sql)을 더하고 sha256 목록에 한 줄을 더한다. 어떤 DB에도 적용된 적 없는"
|
||||
" 파일이라 고쳐야 하면 소유자에게 묻는다.")
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# format — google-java-format on the one edited file
|
||||
|
||||
|
||||
def catalog_version(root: Path, key: str) -> str | None:
|
||||
try:
|
||||
text = (root / CATALOG).read_text(encoding="utf-8")
|
||||
except OSError:
|
||||
return None
|
||||
match = re.search(rf'^{re.escape(key)}\s*=\s*"([^"]+)"', text, re.M)
|
||||
return match.group(1) if match else None
|
||||
|
||||
|
||||
def gradle_cache() -> Path:
|
||||
home = os.environ.get("GRADLE_USER_HOME")
|
||||
return (Path(home) if home else Path.home() / ".gradle") / "caches/modules-2/files-2.1"
|
||||
|
||||
|
||||
def version_key(version: str) -> tuple:
|
||||
return tuple(int(part) if part.isdigit() else -1 for part in re.split(r"[.-]", version))
|
||||
|
||||
|
||||
def newest_jar(cache: Path, group_artifact: str, suffix: str = "") -> Path | None:
|
||||
folder = cache / group_artifact
|
||||
artifact = group_artifact.rsplit("/", 1)[1]
|
||||
versions = sorted((v.name for v in folder.glob("*") if v.name.endswith(suffix)), key=version_key) \
|
||||
if folder.is_dir() else []
|
||||
for version in reversed(versions):
|
||||
jars = sorted(folder.glob(f"{version}/*/{artifact}-{version}.jar"))
|
||||
if jars:
|
||||
return jars[0]
|
||||
return None
|
||||
|
||||
|
||||
def formatter_classpath(root: Path, cache: Path) -> tuple[list[Path] | None, str]:
|
||||
version = catalog_version(root, "googleJavaFormat")
|
||||
if version is None:
|
||||
return None, f"{CATALOG}에 googleJavaFormat 버전이 없다"
|
||||
jars = sorted(cache.glob(f"{GJF_GROUP}/{version}/*/google-java-format-{version}.jar"))
|
||||
if not jars:
|
||||
return None, f"google-java-format {version} jar가 Gradle 캐시({cache})에 없다"
|
||||
guava = newest_jar(cache, "com.google.guava/guava", "-jre")
|
||||
access = newest_jar(cache, "com.google.guava/failureaccess")
|
||||
if guava is None or access is None:
|
||||
return None, "guava jar가 Gradle 캐시에 없다"
|
||||
return [jars[0], guava, access], version
|
||||
|
||||
|
||||
def wants_format(path: str | None) -> bool:
|
||||
return bool(path) and path.startswith("src/") and path.endswith(".java") \
|
||||
and not path.startswith(FORMAT_EXCLUDED) and "/build/" not in path
|
||||
|
||||
|
||||
def format_java(root: Path, path: str, cache: Path | None = None) -> list[str]:
|
||||
"""Format lines for the model. A skip line starts with SKIPPED so the caller can say it once."""
|
||||
classpath, detail = formatter_classpath(root, cache or gradle_cache())
|
||||
if classpath is None:
|
||||
return [f"{SKIPPED}: {detail}. 받거나 설치하지 않는다. desktop `./gradlew spotlessApply`가 맞춘다."]
|
||||
target = root / path
|
||||
before = hashlib.sha256(target.read_bytes()).hexdigest()
|
||||
command = ["java", *GJF_EXPORTS, "-cp", os.pathsep.join(str(jar) for jar in classpath),
|
||||
"com.google.googlejavaformat.java.Main", *GJF_FLAGS, str(target)]
|
||||
try:
|
||||
result = subprocess.run(command, capture_output=True, text=True, timeout=GJF_TIMEOUT)
|
||||
except FileNotFoundError:
|
||||
return [f"{SKIPPED}: `java`가 PATH에 없다. desktop `./gradlew spotlessApply`가 맞춘다."]
|
||||
except subprocess.TimeoutExpired:
|
||||
return [f"{SKIPPED}: google-java-format이 {GJF_TIMEOUT}초 안에 끝나지 않았다."]
|
||||
if result.returncode != 0:
|
||||
errors = [line for line in result.stderr.splitlines() if line.strip()][:3]
|
||||
return [f"google-java-format {detail}가 {path}를 읽지 못했다(문법 오류일 수 있다):", *errors]
|
||||
if hashlib.sha256(target.read_bytes()).hexdigest() != before:
|
||||
return [f"google-java-format {detail}가 {path}를 Spotless와 같은 모양으로 다시 썼다. 다음 Edit 전에 다시 읽는다."]
|
||||
return []
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# N1 — imports of one edited main source against the registry and the layer purity rules
|
||||
|
||||
|
||||
def load_registry(root: Path) -> list[dict]:
|
||||
return json.loads((root / REGISTRY).read_text(encoding="utf-8")).get("modules", [])
|
||||
|
||||
|
||||
def owning_leaf(modules: list[dict], path: str) -> dict | None:
|
||||
owners = [m for m in modules if path.startswith(m["source_path"].rstrip("/") + "/")]
|
||||
return max(owners, key=lambda m: len(m["source_path"])) if owners else None
|
||||
|
||||
|
||||
def package_index(root: Path, modules: list[dict]) -> dict[str, set[str]]:
|
||||
"""Java package → the leaves whose main source set has a class in it."""
|
||||
index: dict[str, set[str]] = {}
|
||||
for module in modules:
|
||||
base = root / module["source_path"] / "src/main/java"
|
||||
for directory, _, names in os.walk(base):
|
||||
if any(name.endswith(".java") for name in names):
|
||||
package = Path(directory).relative_to(base).as_posix().replace("/", ".")
|
||||
index.setdefault(package, set()).add(module["id"])
|
||||
return index
|
||||
|
||||
|
||||
def closure(modules: list[dict], start: str) -> set[str]:
|
||||
edges = {m["id"]: m.get("allowed_dependencies", []) for m in modules}
|
||||
seen, pending = {start}, [start]
|
||||
while pending:
|
||||
for target in edges.get(pending.pop(), []):
|
||||
if target not in seen:
|
||||
seen.add(target)
|
||||
pending.append(target)
|
||||
return seen
|
||||
|
||||
|
||||
def owner_of(index: dict[str, set[str]], name: str) -> tuple[str, set[str]] | None:
|
||||
"""The longest package prefix of an imported name that some leaf owns (handles nested and static)."""
|
||||
parts = name.split(".")
|
||||
for end in range(len(parts), 1, -1):
|
||||
package = ".".join(parts[:end])
|
||||
if package in index:
|
||||
return package, index[package]
|
||||
return None
|
||||
|
||||
|
||||
def forbidden_prefixes(leaf: str) -> tuple[str, tuple[str, ...]] | None:
|
||||
if leaf == "domain-core":
|
||||
return "HARD-STOP 1", DOMAIN_FORBIDDEN
|
||||
if leaf.startswith("application-"):
|
||||
return "HARD-STOP 1·4", APPLICATION_FORBIDDEN
|
||||
if leaf == "shared-contract":
|
||||
return "shared-contract 금지", SHARED_FORBIDDEN
|
||||
if leaf.startswith("adapter-inbound-"):
|
||||
return "HARD-STOP 2", INBOUND_FORBIDDEN
|
||||
return None
|
||||
|
||||
|
||||
def stop_number(leaf: str, target: str) -> str:
|
||||
if (leaf == "domain-core" or leaf.startswith("application-")) and target.startswith("adapter-inbound-"):
|
||||
return "HARD-STOP 3"
|
||||
if leaf.startswith("adapter-inbound-") and target.startswith("adapter-outbound-persistence"):
|
||||
return "HARD-STOP 2"
|
||||
return "HARD-STOP 5"
|
||||
|
||||
|
||||
def boundary_findings(root: Path, path: str, source: str) -> list[str]:
|
||||
if not MAIN_JAVA.match(path):
|
||||
return []
|
||||
modules = load_registry(root)
|
||||
leaf = owning_leaf(modules, path)
|
||||
if leaf is None:
|
||||
return []
|
||||
allowed = closure(modules, leaf["id"])
|
||||
index = package_index(root, modules)
|
||||
rule = forbidden_prefixes(leaf["id"])
|
||||
findings = []
|
||||
for static, name, wildcard in IMPORT.findall(source):
|
||||
imported = name + (".*" if wildcard else "")
|
||||
if rule and any(imported.startswith(prefix) for prefix in rule[1]):
|
||||
findings.append(f"- {rule[0]} 의심: `{leaf['id']}`가 `{imported}`를 import한다.")
|
||||
continue
|
||||
if not name.startswith(PROJECT_PREFIX):
|
||||
continue
|
||||
owner = owner_of(index, name)
|
||||
if owner is None or owner[1] & allowed:
|
||||
continue
|
||||
target = sorted(owner[1])[0]
|
||||
findings.append(f"- {stop_number(leaf['id'], target)} 의심: `{imported}`는 leaf `{target}`의 것인데"
|
||||
f" `{leaf['id']}`의 registry allowed_dependencies(전이 포함)에 없다.")
|
||||
if findings:
|
||||
findings.insert(0, f"레이어 의존 알림(N1) {path}")
|
||||
findings.append("정본은 게이트다: desktop `./gradlew architectureCheck`. 의도한 edge면 registry가 먼저다.")
|
||||
return findings
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# N2 — the document checks, failures only
|
||||
|
||||
|
||||
def wants_doc_check(path: str | None) -> bool:
|
||||
return bool(path) and path.endswith(".md") and "/build/" not in path and not path.startswith(".claude/hook-state/")
|
||||
|
||||
|
||||
def doc_findings(root: Path, path: str) -> list[str]:
|
||||
failures: list[str] = []
|
||||
for script in DOC_CHECKS:
|
||||
try:
|
||||
result = subprocess.run([sys.executable, *script], cwd=root, capture_output=True, text=True,
|
||||
timeout=DOC_TIMEOUT)
|
||||
except subprocess.TimeoutExpired:
|
||||
failures.append(f"- {script[0]}: {DOC_TIMEOUT}초 안에 끝나지 않았다")
|
||||
continue
|
||||
if result.returncode == 0:
|
||||
continue
|
||||
lines = [line.strip() for line in result.stderr.splitlines()
|
||||
if line.startswith(" ") and line.strip()]
|
||||
mine = [line for line in lines if path in line]
|
||||
failures += [f"- {line}" for line in (mine or lines)]
|
||||
if failures:
|
||||
failures.insert(0, f"문서 검사 알림(N2) {path} 편집 뒤 실패 줄:")
|
||||
return failures
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# N5 — Java changed and the desktop has not compiled it since
|
||||
|
||||
|
||||
def ran_desktop_gradle(command: str) -> bool:
|
||||
try:
|
||||
words = shlex.split(command)
|
||||
except ValueError:
|
||||
words = command.split()
|
||||
for position, word in enumerate(words):
|
||||
if word.endswith("ssh"):
|
||||
hosts = [w for w in words[position + 1:position + 5] if not w.startswith("-")][:2]
|
||||
if any(DESKTOP_HOST.search(host) for host in hosts) and "gradlew" in command:
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def turn_end_reason(state: dict) -> str | None:
|
||||
edits = state.get("java_edits") or []
|
||||
if not edits or state.get("reminded"):
|
||||
return None
|
||||
shown = ", ".join(f"`{edit}`" for edit in edits[:3]) + (f" 외 {len(edits) - 3}개" if len(edits) > 3 else "")
|
||||
return (f"[N5 턴 끝 알림] 이 세션에서 Java 파일 {len(edits)}개를 고쳤고({shown}) 그 뒤 desktop Gradle 실행이 없다. "
|
||||
"컴파일과 테스트는 노트북이 아니라 desktop에서 소유 leaf의 `<gradle-path>:check`로 한다"
|
||||
"(docs/work/operate.md 4.1절). 이번 턴에 돌릴 수 없으면 완료를 말하지 말고, 보고의 확인 줄에 돌리지 못한 것과"
|
||||
" 이유를 적는다(HARD-STOP 6). 이 알림은 다음 Java 편집 전까지 한 번만 나온다.")
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# events
|
||||
|
||||
|
||||
def pre_edit(payload: dict) -> int:
|
||||
message = h13_message(project_root(payload), edited_path(payload))
|
||||
if message:
|
||||
print(message, file=sys.stderr)
|
||||
return 2
|
||||
return 0
|
||||
|
||||
|
||||
def post_edit(payload: dict) -> int:
|
||||
root = project_root(payload)
|
||||
path = edited_path(payload)
|
||||
if path is None or not (root / path).is_file():
|
||||
return 0
|
||||
lines: list[str] = []
|
||||
if wants_format(path):
|
||||
state = load_state(root, payload.get("session_id", ""))
|
||||
formatted = format_java(root, path)
|
||||
if formatted and formatted[0].startswith(SKIPPED):
|
||||
# The reason does not change within a session; saying it on every edit is noise.
|
||||
formatted = [] if state.get("format_skip_reported") else formatted
|
||||
state["format_skip_reported"] = True
|
||||
lines += formatted
|
||||
if path not in state["java_edits"]:
|
||||
state["java_edits"].append(path)
|
||||
state["reminded"] = False
|
||||
save_state(root, payload.get("session_id", ""), state)
|
||||
lines += boundary_findings(root, path, (root / path).read_text(encoding="utf-8"))
|
||||
if wants_doc_check(path):
|
||||
lines += doc_findings(root, path)
|
||||
if lines:
|
||||
print(context("PostToolUse", lines))
|
||||
return 0
|
||||
|
||||
|
||||
def post_bash(payload: dict) -> int:
|
||||
command = (payload.get("tool_input") or {}).get("command", "")
|
||||
if ran_desktop_gradle(command):
|
||||
root = project_root(payload)
|
||||
state = load_state(root, payload.get("session_id", ""))
|
||||
state["java_edits"] = []
|
||||
state["reminded"] = False
|
||||
save_state(root, payload.get("session_id", ""), state)
|
||||
return 0
|
||||
|
||||
|
||||
def stop(payload: dict) -> int:
|
||||
if payload.get("stop_hook_active"):
|
||||
return 0
|
||||
root = project_root(payload)
|
||||
state = load_state(root, payload.get("session_id", ""))
|
||||
reason = turn_end_reason(state)
|
||||
if reason:
|
||||
state["reminded"] = True
|
||||
save_state(root, payload.get("session_id", ""), state)
|
||||
print(json.dumps({"decision": "block", "reason": reason}, ensure_ascii=False))
|
||||
return 0
|
||||
|
||||
|
||||
EVENTS = {"pre-edit": pre_edit, "post-edit": post_edit, "post-bash": post_bash, "stop": stop}
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
if len(argv) != 1 or argv[0] not in EVENTS:
|
||||
print(f"usage: hooks.py {{{'|'.join(EVENTS)}}} < hook-input.json", file=sys.stderr)
|
||||
return 1
|
||||
try:
|
||||
payload = json.load(sys.stdin)
|
||||
except ValueError:
|
||||
return 0
|
||||
return EVENTS[argv[0]](payload if isinstance(payload, dict) else {})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
@@ -439,6 +439,64 @@ class ReadmeTest(RepositoryTestCase):
|
||||
self.assertFailsWith(self.repo.run(("readme",)), "루트 README가 없다")
|
||||
|
||||
|
||||
class LinkTest(RepositoryTestCase):
|
||||
def errors_for(self, text: str, path: str = "src/app/AGENTS.md") -> list[str]:
|
||||
self.repo.write(path, KOREAN + text)
|
||||
return self.repo.run(("link",))
|
||||
|
||||
def test_a_relative_link_to_a_missing_file_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for("[설계](README.md)를 본다.\n"), "없는 곳을 가리키는 상대 링크다: README.md")
|
||||
|
||||
def test_a_relative_link_to_a_tracked_file_passes(self) -> None:
|
||||
self.repo.write("src/app/README.md", KOREAN)
|
||||
self.assertEqual(self.errors_for("[설계](README.md#결정)를 본다.\n"), [])
|
||||
|
||||
def test_a_link_up_the_tree_resolves_from_the_document_folder(self) -> None:
|
||||
self.assertEqual(self.errors_for("[살아 있는 문서](../../docs/live.md)를 본다.\n"), [])
|
||||
|
||||
def test_a_link_out_of_the_repository_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for("[밖](../../../outside.md)를 본다.\n"), "../../../outside.md")
|
||||
|
||||
def test_a_folder_left_empty_on_disk_fails(self) -> None:
|
||||
(self.repo.root / "src/app/moved").mkdir(parents=True)
|
||||
self.assertFailsWith(self.errors_for("[옮김](moved/)을 본다.\n"), "moved/")
|
||||
|
||||
def test_urls_anchors_code_and_history_quotes_are_skipped(self) -> None:
|
||||
text = ("[웹](https://example.com/x) [절](#절) `[코드](gone.md)`\n"
|
||||
"```text\n[블록](gone.md)\n```\n> 이력: [옛 문서](gone.md)는 지웠다.\n")
|
||||
self.assertEqual(self.errors_for(text), [])
|
||||
|
||||
def test_a_record_is_not_checked(self) -> None:
|
||||
self.repo.write("docs/design/2026-08-11-x-design.md", head() + "[옛](gone.md)\n")
|
||||
self.assertEqual(self.repo.run(("link",)), [])
|
||||
|
||||
|
||||
class StyleTest(RepositoryTestCase):
|
||||
def errors_for(self, text: str, path: str = "docs/guide.md") -> list[str]:
|
||||
self.repo.write(path, KOREAN + text)
|
||||
return self.repo.run(("style",))
|
||||
|
||||
def test_a_polite_sentence_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for("이 runbook은 다음 alert에서 발동됩니다.\n"), "높임 문체다")
|
||||
|
||||
def test_a_polite_request_at_the_end_of_a_line_fails(self) -> None:
|
||||
self.assertFailsWith(self.errors_for("- 설정을 바꾼 뒤 다시 실행하세요\n"), "…하세요")
|
||||
|
||||
def test_the_plain_style_passes(self) -> None:
|
||||
self.assertEqual(self.errors_for("이 runbook은 다음 alert가 울리면 쓴다.\n"), [])
|
||||
|
||||
def test_quoted_code_and_history_mentions_are_skipped(self) -> None:
|
||||
text = ("문체는 「~한다」다. 「~합니다」와 섞지 않는다.\n"
|
||||
"응답 본문은 \"요청을 처리할 수 없습니다.\"다. `처리합니다.`는 코드다.\n"
|
||||
"```json\n{\"message\": \"처리할 수 없습니다.\"}\n```\n"
|
||||
"> 이력: 이 문서는 예전에 「~합니다」로 썼습니다.\n")
|
||||
self.assertEqual(self.errors_for(text), [])
|
||||
|
||||
def test_a_record_is_not_checked(self) -> None:
|
||||
self.repo.write("docs/design/2026-08-11-x-design.md", head() + "이 설계는 채택되었습니다.\n")
|
||||
self.assertEqual(self.repo.run(("style",)), [])
|
||||
|
||||
|
||||
class CommandLineTest(unittest.TestCase):
|
||||
def test_an_unknown_check_is_a_usage_error(self) -> None:
|
||||
self.assertEqual(check_docs.main(["--only", "spelling"]), 2)
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
"""scripts/check-work-docs.py의 시험. 고장 낸 지침 배치에서 실패하고, 맞는 배치에서 통과하는지 본다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import io
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from contextlib import redirect_stderr, redirect_stdout
|
||||
from pathlib import Path
|
||||
|
||||
SCRIPTS = Path(__file__).resolve().parent.parent
|
||||
_spec = importlib.util.spec_from_file_location("check_work_docs", SCRIPTS / "check-work-docs.py")
|
||||
check_work_docs = importlib.util.module_from_spec(_spec)
|
||||
sys.modules["check_work_docs"] = check_work_docs
|
||||
_spec.loader.exec_module(check_work_docs)
|
||||
|
||||
PLAYBOOK = "".join(f"## {heading}\n\n- 한 줄.\n\n" for heading in check_work_docs.SKELETON)
|
||||
|
||||
|
||||
class Repository:
|
||||
"""A throwaway repository with the smallest work manual the checker accepts."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._directory = tempfile.TemporaryDirectory()
|
||||
self.root = Path(self._directory.name)
|
||||
self.write("AGENTS.md", "# 정본\n\n- 지도 한 줄.\n")
|
||||
self.write("CLAUDE.md", "@AGENTS.md\n\n- Claude 전용 한 줄.\n")
|
||||
self.write("docs/work/README.md", "# 작업 매뉴얼\n")
|
||||
self.write("docs/work/evidence.md", "# 근거\n\n`1101/05-18`은 여기에 둔다.\n")
|
||||
for name in check_work_docs.PLAYBOOKS:
|
||||
self.write(f"docs/work/{name}", f"# {name}\n\n{PLAYBOOK}")
|
||||
for name in check_work_docs.REFERENCES:
|
||||
self.write(f"docs/work/{name}", "# 참고\n")
|
||||
self.write("src/app/AGENTS.md", "# app\n\n- 지역 규칙.\n")
|
||||
self.write("src/app/CLAUDE.md", "@AGENTS.md\n")
|
||||
self.saved = {name: getattr(check_work_docs, name) for name in ("REPO_ROOT", "MAP", "CLAUDE_ENTRY", "WORK", "README")}
|
||||
check_work_docs.REPO_ROOT = self.root
|
||||
check_work_docs.MAP = self.root / "AGENTS.md"
|
||||
check_work_docs.CLAUDE_ENTRY = self.root / "CLAUDE.md"
|
||||
check_work_docs.WORK = self.root / "docs/work"
|
||||
check_work_docs.README = check_work_docs.WORK / "README.md"
|
||||
|
||||
def write(self, path: str, text: str) -> None:
|
||||
target = self.root / path
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
target.write_text(text, encoding="utf-8")
|
||||
|
||||
def run(self) -> tuple[int, str]:
|
||||
out, err = io.StringIO(), io.StringIO()
|
||||
argv = sys.argv
|
||||
sys.argv = ["check-work-docs.py"]
|
||||
try:
|
||||
with redirect_stdout(out), redirect_stderr(err):
|
||||
code = check_work_docs.main()
|
||||
finally:
|
||||
sys.argv = argv
|
||||
return code, err.getvalue()
|
||||
|
||||
def close(self) -> None:
|
||||
for name, value in self.saved.items():
|
||||
setattr(check_work_docs, name, value)
|
||||
self._directory.cleanup()
|
||||
|
||||
|
||||
class CheckWorkDocsTest(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.repo = Repository()
|
||||
self.addCleanup(self.repo.close)
|
||||
|
||||
def assertFailsWith(self, fragment: str) -> None:
|
||||
code, err = self.repo.run()
|
||||
self.assertEqual(code, 1, err)
|
||||
self.assertIn(fragment, err)
|
||||
|
||||
def test_the_smallest_valid_manual_passes(self) -> None:
|
||||
self.assertEqual(self.repo.run(), (0, ""))
|
||||
|
||||
def test_a_map_over_forty_lines_fails(self) -> None:
|
||||
self.repo.write("AGENTS.md", "# 정본\n" + "- 줄.\n" * 40)
|
||||
self.assertFailsWith("AGENTS.md: 41 lines, limit 40")
|
||||
|
||||
def test_a_claude_entry_over_ten_lines_fails(self) -> None:
|
||||
self.repo.write("CLAUDE.md", "@AGENTS.md\n" + "- 줄.\n" * 10)
|
||||
self.assertFailsWith("CLAUDE.md: 11 lines, limit 10")
|
||||
|
||||
def test_a_claude_entry_that_does_not_import_the_map_fails(self) -> None:
|
||||
self.repo.write("CLAUDE.md", "# 지도\n\n@AGENTS.md\n")
|
||||
self.assertFailsWith("CLAUDE.md: the first line must be '@AGENTS.md'")
|
||||
|
||||
def test_the_entry_path_counts_the_map_the_claude_entry_the_readme_and_one_playbook(self) -> None:
|
||||
# Each file's own limit keeps the sum under ENTRY_PATH_LIMIT today, so lower it to see the sum.
|
||||
lines = sum(len((self.repo.root / name).read_text(encoding="utf-8").splitlines())
|
||||
for name in ("AGENTS.md", "CLAUDE.md", "docs/work/README.md", "docs/work/improve.md"))
|
||||
original = check_work_docs.ENTRY_PATH_LIMIT
|
||||
check_work_docs.ENTRY_PATH_LIMIT = lines - 1
|
||||
self.addCleanup(setattr, check_work_docs, "ENTRY_PATH_LIMIT", original)
|
||||
self.assertFailsWith(f"docs/work/improve.md: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {lines} lines")
|
||||
|
||||
def test_a_folder_rule_book_over_two_hundred_lines_fails(self) -> None:
|
||||
self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 200)
|
||||
self.assertFailsWith("src/app/AGENTS.md: 201 lines, limit 200")
|
||||
|
||||
def test_a_folder_rule_book_of_two_hundred_lines_passes(self) -> None:
|
||||
self.repo.write("src/app/AGENTS.md", "# app\n" + "- 규칙.\n" * 199)
|
||||
self.assertEqual(self.repo.run(), (0, ""))
|
||||
|
||||
def test_a_folder_rule_book_without_its_claude_import_fails(self) -> None:
|
||||
self.repo.write("src/web/AGENTS.md", "# web\n")
|
||||
self.assertFailsWith("src/web/CLAUDE.md: missing; it must be the one line '@AGENTS.md'")
|
||||
|
||||
def test_a_folder_claude_file_that_holds_rules_fails(self) -> None:
|
||||
self.repo.write("src/app/CLAUDE.md", "@AGENTS.md\n\n- 여기에도 규칙을 쓴다.\n")
|
||||
self.assertFailsWith("src/app/CLAUDE.md: must be exactly '@AGENTS.md'")
|
||||
|
||||
def test_a_folder_claude_file_without_a_rule_book_fails(self) -> None:
|
||||
self.repo.write("src/old/CLAUDE.md", "@AGENTS.md\n")
|
||||
self.assertFailsWith("src/old/CLAUDE.md: imports src/old/AGENTS.md, which does not exist")
|
||||
|
||||
def test_build_output_is_not_a_folder_rule_book(self) -> None:
|
||||
self.repo.write("src/app/build/tmp/AGENTS.md", "# 복사본\n")
|
||||
self.assertEqual(self.repo.run()[0], 0)
|
||||
|
||||
def test_a_history_id_in_a_folder_rule_book_fails(self) -> None:
|
||||
self.repo.write("src/app/AGENTS.md", "# app\n\n- 리뷰 05-18에서 정했다.\n")
|
||||
self.assertFailsWith("src/app/AGENTS.md:3")
|
||||
|
||||
def test_a_history_id_in_a_claude_rule_skill_or_agent_fails(self) -> None:
|
||||
for path in (".claude/rules/x.md", ".claude/skills/x/SKILL.md", ".claude/agents/x.md"):
|
||||
with self.subTest(path=path):
|
||||
self.repo.write(path, "# 규칙\n\n- RR-03-03에서 고쳤다.\n")
|
||||
self.assertFailsWith(f"{path}:3")
|
||||
(self.repo.root / path).unlink()
|
||||
|
||||
def test_local_claude_state_is_not_checked(self) -> None:
|
||||
self.repo.write(".claude/worktrees/other/AGENTS.md", "# 다른 worktree\n\n- 리뷰 05-18.\n")
|
||||
self.assertEqual(self.repo.run()[0], 0)
|
||||
|
||||
def test_a_broken_link_in_a_folder_rule_book_fails(self) -> None:
|
||||
self.repo.write("src/app/AGENTS.md", "# app\n\n[설계](README.md)\n")
|
||||
self.assertFailsWith("src/app/AGENTS.md:3: broken relative link 'README.md'")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,95 @@
|
||||
"""`.claude/`의 서브에이전트 정의와 스킬이 소유자 결정(2026-11-07)대로인지 본다.
|
||||
|
||||
결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절).
|
||||
새 스킬은 모두 모델이 부를 수 있고, 설명에 발동 조건을 문단으로 적는다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO = Path(__file__).resolve().parent.parent.parent
|
||||
AGENTS = REPO / ".claude/agents"
|
||||
SKILLS = REPO / ".claude/skills"
|
||||
# Claude Code cuts a skill description at this many characters in the listing.
|
||||
DESCRIPTION_LIMIT = 1536
|
||||
WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
|
||||
|
||||
|
||||
def front_matter(path: Path) -> dict[str, str]:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
match = re.match(r"^---\n(.*?)\n---\n", text, re.S)
|
||||
if not match:
|
||||
return {}
|
||||
fields = {}
|
||||
for line in match.group(1).splitlines():
|
||||
key, _, value = line.partition(":")
|
||||
fields[key.strip()] = value.strip()
|
||||
return fields
|
||||
|
||||
|
||||
class SubagentTest(unittest.TestCase):
|
||||
def test_the_agent_tool_is_no_longer_denied(self) -> None:
|
||||
settings = json.loads((REPO / ".claude/settings.json").read_text(encoding="utf-8"))
|
||||
deny = settings.get("permissions", {}).get("deny", [])
|
||||
self.assertFalse([rule for rule in deny if rule == "Agent" or rule.startswith("Agent(")])
|
||||
|
||||
def test_each_definition_names_itself_and_says_when_to_use_it(self) -> None:
|
||||
definitions = sorted(AGENTS.glob("*.md"))
|
||||
self.assertEqual([path.stem for path in definitions], ["arch-reviewer", "code-simplifier", "verify-api"])
|
||||
for path in definitions:
|
||||
fields = front_matter(path)
|
||||
self.assertEqual(fields.get("name"), path.stem, path)
|
||||
self.assertRegex(fields.get("description", ""), r"쓴다", path)
|
||||
self.assertTrue(fields.get("tools"), f"{path} must list its tools; an empty list inherits every tool")
|
||||
|
||||
def test_no_subagent_can_edit_files(self) -> None:
|
||||
for path in AGENTS.glob("*.md"):
|
||||
tools = {tool.strip() for tool in front_matter(path).get("tools", "").split(",")}
|
||||
self.assertFalse(tools & WRITE_TOOLS, f"{path} returns results only; it must not hold {tools & WRITE_TOOLS}")
|
||||
|
||||
def test_the_reviewers_have_no_shell_that_could_change_the_tree_except_read_commands(self) -> None:
|
||||
self.assertNotIn("Bash", front_matter(AGENTS / "code-simplifier.md")["tools"])
|
||||
reviewer = (AGENTS / "arch-reviewer.md").read_text(encoding="utf-8")
|
||||
self.assertIn("파일을 쓰거나 고치지 않는다", reviewer)
|
||||
|
||||
def test_verify_api_runs_the_app_on_the_desktop_under_the_shared_lock(self) -> None:
|
||||
text = (AGENTS / "verify-api.md").read_text(encoding="utf-8")
|
||||
for fragment in ("docs/work/operate.md", "flock /tmp/claude-gates/heavy.lock", "scripts/bootstrap-local.sh",
|
||||
"stash@{0}", "down"):
|
||||
self.assertIn(fragment, text)
|
||||
|
||||
|
||||
class SkillTest(unittest.TestCase):
|
||||
CANON = {"new-feature": "docs/work/new-feature.md", "desktop-gates": "docs/work/operate.md"}
|
||||
|
||||
def test_the_repository_skills_are_the_two_the_manual_names(self) -> None:
|
||||
self.assertEqual(sorted(path.parent.name for path in SKILLS.glob("*/SKILL.md")), sorted(self.CANON))
|
||||
|
||||
def test_each_skill_is_model_invoked_and_says_when_in_its_description(self) -> None:
|
||||
for name in self.CANON:
|
||||
fields = front_matter(SKILLS / name / "SKILL.md")
|
||||
self.assertEqual(fields.get("name"), name)
|
||||
self.assertNotIn("disable-model-invocation", fields)
|
||||
description = fields.get("description", "")
|
||||
self.assertLessEqual(len(description), DESCRIPTION_LIMIT, name)
|
||||
self.assertIn("쓴다", description, f"{name}: say when to use it")
|
||||
self.assertIn("부른다", description, f"{name}: say what the user says that calls it")
|
||||
|
||||
def test_each_skill_points_at_its_canonical_playbook_instead_of_copying_it(self) -> None:
|
||||
for name, canon in self.CANON.items():
|
||||
body = (SKILLS / name / "SKILL.md").read_text(encoding="utf-8")
|
||||
self.assertIn(f"정본은 `{canon}`", body)
|
||||
self.assertIn("정본이 맞다", body)
|
||||
|
||||
def test_the_uninstalled_skill_lock_is_gone(self) -> None:
|
||||
self.assertFalse((REPO / "skills-lock.json").exists())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,400 @@
|
||||
"""scripts/hooks/hooks.py의 시험. 고장 낸 입력에서 알림·차단이 나오고, 맞는 입력에서 조용한지 본다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import stat
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import textwrap
|
||||
import unittest
|
||||
from contextlib import redirect_stderr, redirect_stdout
|
||||
from pathlib import Path
|
||||
from unittest import mock
|
||||
|
||||
SCRIPTS = Path(__file__).resolve().parent.parent
|
||||
REPO = SCRIPTS.parent
|
||||
_spec = importlib.util.spec_from_file_location("hooks", SCRIPTS / "hooks/hooks.py")
|
||||
hooks = importlib.util.module_from_spec(_spec)
|
||||
sys.modules["hooks"] = hooks
|
||||
_spec.loader.exec_module(hooks)
|
||||
|
||||
REGISTRY = {"modules": [
|
||||
{"id": "domain-core", "gradle_path": ":domain-core", "source_path": "src/domain-core", "allowed_dependencies": []},
|
||||
{"id": "shared-contract", "gradle_path": ":shared-contract", "source_path": "src/shared-contract",
|
||||
"allowed_dependencies": []},
|
||||
{"id": "application-core", "gradle_path": ":application-core", "source_path": "src/application-core",
|
||||
"allowed_dependencies": ["domain-core", "shared-contract"]},
|
||||
{"id": "adapter-inbound-web", "gradle_path": ":adapter:inbound:web", "source_path": "src/adapter/inbound/web",
|
||||
"allowed_dependencies": ["application-core"]},
|
||||
{"id": "adapter-outbound-persistence-jpa", "gradle_path": ":adapter:outbound:persistence-jpa",
|
||||
"source_path": "src/adapter/outbound/persistence-jpa", "allowed_dependencies": ["application-core"]},
|
||||
]}
|
||||
PACKAGES = {
|
||||
"src/domain-core": "dev/caskeleton/domain/order/Order.java",
|
||||
"src/shared-contract": "dev/caskeleton/shared/error/ApiErrorCode.java",
|
||||
"src/application-core": "dev/caskeleton/application/order/PlaceOrderUseCase.java",
|
||||
"src/adapter/inbound/web": "dev/caskeleton/adapter/inbound/web/order/OrderRequest.java",
|
||||
"src/adapter/outbound/persistence-jpa": "dev/caskeleton/adapter/outbound/persistence/order/OrderEntity.java",
|
||||
}
|
||||
|
||||
|
||||
class Repository:
|
||||
"""A throwaway project with a registry, one class per leaf and the migration manifest."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._directory = tempfile.TemporaryDirectory()
|
||||
self.root = Path(self._directory.name).resolve()
|
||||
self.write(hooks.REGISTRY, json.dumps(REGISTRY))
|
||||
for leaf, source in PACKAGES.items():
|
||||
package = Path(source).parent.as_posix().replace("/", ".")
|
||||
self.write(f"{leaf}/src/main/java/{source}", f"package {package};\n\nclass {Path(source).stem} {{}}\n")
|
||||
self.write(hooks.MIGRATION_MANIFEST,
|
||||
"# comment line\n" + "a" * 64 + " jpa/core/V1__initialize_or_adopt.sql\n")
|
||||
self.write(hooks.CATALOG, 'googleJavaFormat = "1.35.0"\n')
|
||||
|
||||
def write(self, path: str, text: str) -> Path:
|
||||
target = self.root / path
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
target.write_text(text, encoding="utf-8")
|
||||
return target
|
||||
|
||||
def payload(self, path: str, tool: str = "Edit", **extra) -> dict:
|
||||
return {"session_id": "s1", "cwd": str(self.root), "tool_name": tool,
|
||||
"tool_input": {"file_path": str(self.root / path)}, **extra}
|
||||
|
||||
def close(self) -> None:
|
||||
self._directory.cleanup()
|
||||
|
||||
|
||||
def run_event(event: str, payload: dict, environment: dict | None = None) -> tuple[int, str, str]:
|
||||
out, err = io.StringIO(), io.StringIO()
|
||||
with mock.patch.dict(os.environ, environment or {}, clear=False), \
|
||||
mock.patch.object(sys, "stdin", io.StringIO(json.dumps(payload))), redirect_stdout(out), redirect_stderr(err):
|
||||
os.environ.pop("CLAUDE_PROJECT_DIR", None)
|
||||
code = hooks.main([event])
|
||||
return code, out.getvalue(), err.getvalue()
|
||||
|
||||
|
||||
def fake_cache(home: Path, version: str = "1.35.0") -> Path:
|
||||
"""A Gradle user home whose module cache holds the jars the formatter looks for."""
|
||||
cache = home / "caches/modules-2/files-2.1"
|
||||
for group, artifact_version in (("com.google.googlejavaformat/google-java-format", version),
|
||||
("com.google.guava/guava", "33.6.0-jre"),
|
||||
("com.google.guava/guava", "33.2.1-android"),
|
||||
("com.google.guava/failureaccess", "1.0.3")):
|
||||
artifact = group.rsplit("/", 1)[1]
|
||||
jar = cache / group / artifact_version / "0123abcd" / f"{artifact}-{artifact_version}.jar"
|
||||
jar.parent.mkdir(parents=True, exist_ok=True)
|
||||
jar.write_bytes(b"jar")
|
||||
return cache
|
||||
|
||||
|
||||
def fake_java(folder: Path, body: str) -> str:
|
||||
"""A `java` on PATH that records its arguments in args.json, then runs `body` (Python) on the file."""
|
||||
folder.mkdir(parents=True, exist_ok=True)
|
||||
script = folder / "java"
|
||||
script.write_text(textwrap.dedent(f"""\
|
||||
#!{sys.executable}
|
||||
import json, sys
|
||||
from pathlib import Path
|
||||
Path({str(folder / 'args.json')!r}).write_text(json.dumps(sys.argv[1:]))
|
||||
target = Path(sys.argv[-1])
|
||||
{body}
|
||||
"""), encoding="utf-8")
|
||||
script.chmod(script.stat().st_mode | stat.S_IXUSR)
|
||||
return f"{folder}{os.pathsep}{os.environ.get('PATH', '')}"
|
||||
|
||||
|
||||
def added_context(stdout: str) -> str:
|
||||
return json.loads(stdout)["hookSpecificOutput"]["additionalContext"] if stdout else ""
|
||||
|
||||
|
||||
class RepositoryTestCase(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.repo = Repository()
|
||||
self.addCleanup(self.repo.close)
|
||||
# The formatter is tested on its own; elsewhere a `java` that changes nothing keeps post-edit quiet.
|
||||
self.cache = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.cache.cleanup)
|
||||
home = Path(self.cache.name)
|
||||
fake_cache(home)
|
||||
self.environment = {"GRADLE_USER_HOME": str(home), "PATH": fake_java(home / "quiet-java", "pass")}
|
||||
|
||||
|
||||
class MigrationGuardTest(RepositoryTestCase):
|
||||
"""H13 — PreToolUse blocks an edit of an applied migration, and only that."""
|
||||
|
||||
MIGRATION = "src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/jpa/core/V1__initialize_or_adopt.sql"
|
||||
|
||||
def test_editing_an_applied_migration_is_blocked_with_the_way_out(self) -> None:
|
||||
self.repo.write(self.MIGRATION, "create table x();\n")
|
||||
code, _, err = run_event("pre-edit", self.repo.payload(self.MIGRATION))
|
||||
self.assertEqual(code, 2)
|
||||
self.assertIn("[H13 적용된 migration 편집 금지]", err)
|
||||
self.assertIn("새 버전 파일", err)
|
||||
|
||||
def test_a_migration_in_another_leaf_is_found_by_its_manifest_key(self) -> None:
|
||||
path = "src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/core/V1__initialize_or_adopt.sql"
|
||||
self.assertEqual(run_event("pre-edit", self.repo.payload(path, tool="Write"))[0], 2)
|
||||
|
||||
def test_a_new_migration_version_is_allowed(self) -> None:
|
||||
path = self.MIGRATION.replace("V1__initialize_or_adopt", "V3__add_column")
|
||||
self.assertEqual(run_event("pre-edit", self.repo.payload(path, tool="Write")), (0, "", ""))
|
||||
|
||||
def test_other_files_and_other_tools_are_allowed(self) -> None:
|
||||
self.assertEqual(run_event("pre-edit", self.repo.payload("docs/x.md"))[0], 0)
|
||||
self.assertEqual(run_event("pre-edit", self.repo.payload(self.MIGRATION, tool="Read"))[0], 0)
|
||||
|
||||
|
||||
class FormatterTest(RepositoryTestCase):
|
||||
"""The formatter runs one JVM on one file with the jar Gradle cached; it never downloads one."""
|
||||
|
||||
SOURCE = "src/domain-core/src/main/java/dev/caskeleton/domain/order/Order.java"
|
||||
|
||||
def fake_cache(self, version: str = "1.35.0") -> Path:
|
||||
return fake_cache(Path(tempfile.mkdtemp(dir=self.cache.name)), version)
|
||||
|
||||
def fake_java(self, body: str) -> dict:
|
||||
folder = Path(tempfile.mkdtemp(dir=self.cache.name))
|
||||
self.args_file = folder / "args.json"
|
||||
return {"PATH": fake_java(folder, body)}
|
||||
|
||||
def test_the_classpath_is_the_catalog_version_and_the_newest_jre_guava(self) -> None:
|
||||
classpath, version = hooks.formatter_classpath(self.repo.root, self.fake_cache())
|
||||
self.assertEqual(version, "1.35.0")
|
||||
self.assertEqual([jar.name for jar in classpath],
|
||||
["google-java-format-1.35.0.jar", "guava-33.6.0-jre.jar", "failureaccess-1.0.3.jar"])
|
||||
|
||||
def test_a_cache_without_the_catalog_version_skips_and_says_so(self) -> None:
|
||||
lines = hooks.format_java(self.repo.root, self.SOURCE, self.fake_cache(version="1.28.0"))
|
||||
self.assertEqual(len(lines), 1)
|
||||
self.assertIn("google-java-format 1.35.0 jar가 Gradle 캐시", lines[0])
|
||||
self.assertIn("받거나 설치하지 않는다", lines[0])
|
||||
|
||||
def test_the_formatter_gets_the_spotless_flags_and_the_one_file(self) -> None:
|
||||
cache = self.fake_cache()
|
||||
with mock.patch.dict(os.environ, self.fake_java("pass")):
|
||||
self.assertEqual(hooks.format_java(self.repo.root, self.SOURCE, cache), [])
|
||||
args = json.loads(self.args_file.read_text())
|
||||
self.assertEqual(args[-3:], ["--skip-reflowing-long-strings", "--replace", str(self.repo.root / self.SOURCE)])
|
||||
self.assertIn("com.google.googlejavaformat.java.Main", args)
|
||||
|
||||
def test_a_rewritten_file_tells_the_model_to_read_it_again(self) -> None:
|
||||
cache = self.fake_cache()
|
||||
with mock.patch.dict(os.environ, self.fake_java("target.write_text(target.read_text() + '\\n')")):
|
||||
lines = hooks.format_java(self.repo.root, self.SOURCE, cache)
|
||||
self.assertEqual(len(lines), 1)
|
||||
self.assertIn("다시 읽는다", lines[0])
|
||||
|
||||
def test_a_formatter_error_is_reported_with_its_first_lines(self) -> None:
|
||||
cache = self.fake_cache()
|
||||
body = "sys.stderr.write('Order.java:3:1: error: class, interface, enum, or record expected\\n'); sys.exit(1)"
|
||||
with mock.patch.dict(os.environ, self.fake_java(body)):
|
||||
lines = hooks.format_java(self.repo.root, self.SOURCE, cache)
|
||||
self.assertIn("읽지 못했다", lines[0])
|
||||
self.assertIn("error: class, interface", lines[1])
|
||||
|
||||
def test_a_skipped_format_is_said_once_per_session(self) -> None:
|
||||
environment = {"GRADLE_USER_HOME": str(Path(tempfile.mkdtemp(dir=self.cache.name)))}
|
||||
first = added_context(run_event("post-edit", self.repo.payload(self.SOURCE), environment)[1])
|
||||
second = run_event("post-edit", self.repo.payload(self.SOURCE), environment)[1]
|
||||
self.assertIn("포맷을 건너뛰었다", first)
|
||||
self.assertEqual(second, "")
|
||||
|
||||
def test_build_logic_and_non_java_files_are_not_formatted(self) -> None:
|
||||
self.assertFalse(hooks.wants_format("src/build-logic/src/main/java/A.java"))
|
||||
self.assertFalse(hooks.wants_format("src/app/build/generated/A.java"))
|
||||
self.assertFalse(hooks.wants_format("docs/a.md"))
|
||||
self.assertTrue(hooks.wants_format(self.SOURCE))
|
||||
|
||||
@unittest.skipUnless(hooks.formatter_classpath(REPO, hooks.gradle_cache())[0], "no google-java-format jar in the Gradle cache")
|
||||
def test_the_real_formatter_matches_spotless_on_a_badly_indented_file(self) -> None:
|
||||
# Only on a machine whose Gradle cache holds the catalog version (the owner's laptop).
|
||||
self.repo.write(self.SOURCE, "package dev.caskeleton.domain.order;\nimport java.util.List;\n"
|
||||
"class Order{ List<String> lines(){return List.of(\"a\");}}\n")
|
||||
lines = hooks.format_java(self.repo.root, self.SOURCE, hooks.gradle_cache())
|
||||
self.assertIn("다시 썼다", lines[0])
|
||||
self.assertEqual((self.repo.root / self.SOURCE).read_text(), textwrap.dedent("""\
|
||||
package dev.caskeleton.domain.order;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
class Order {
|
||||
List<String> lines() {
|
||||
return List.of("a");
|
||||
}
|
||||
}
|
||||
"""))
|
||||
|
||||
|
||||
class BoundaryNudgeTest(RepositoryTestCase):
|
||||
"""N1 — imports of one main source against the registry and the purity lists."""
|
||||
|
||||
def nudge(self, leaf: str, relative: str, imports: str) -> str:
|
||||
package = Path(relative).parent.as_posix().replace("/", ".")
|
||||
path = f"{leaf}/src/main/java/{relative}"
|
||||
self.repo.write(path, f"package {package};\n\n{imports}\nclass {Path(relative).stem} {{}}\n")
|
||||
code, out, _ = run_event("post-edit", self.repo.payload(path), self.environment)
|
||||
self.assertEqual(code, 0)
|
||||
return added_context(out)
|
||||
|
||||
def test_spring_in_the_domain_is_hard_stop_1(self) -> None:
|
||||
text = self.nudge("src/domain-core", "dev/caskeleton/domain/order/Line.java",
|
||||
"import org.springframework.stereotype.Component;")
|
||||
self.assertIn("HARD-STOP 1 의심: `domain-core`가 `org.springframework.stereotype.Component`", text)
|
||||
self.assertIn("architectureCheck", text)
|
||||
|
||||
def test_an_inbound_dto_in_the_application_is_hard_stop_3(self) -> None:
|
||||
text = self.nudge("src/application-core", "dev/caskeleton/application/order/Place.java",
|
||||
"import dev.caskeleton.adapter.inbound.web.order.OrderRequest;")
|
||||
self.assertIn("HARD-STOP 3 의심: `dev.caskeleton.adapter.inbound.web.order.OrderRequest`는 leaf "
|
||||
"`adapter-inbound-web`의 것인데 `application-core`", text)
|
||||
|
||||
def test_a_persistence_entity_in_a_controller_is_hard_stop_2(self) -> None:
|
||||
text = self.nudge("src/adapter/inbound/web", "dev/caskeleton/adapter/inbound/web/order/OrderController.java",
|
||||
"import dev.caskeleton.adapter.outbound.persistence.order.OrderEntity;\n"
|
||||
"import org.springframework.data.repository.CrudRepository;")
|
||||
self.assertIn("HARD-STOP 2 의심: `dev.caskeleton.adapter.outbound.persistence.order.OrderEntity`", text)
|
||||
self.assertIn("HARD-STOP 2 의심: `adapter-inbound-web`가 `org.springframework.data.repository.CrudRepository`", text)
|
||||
|
||||
def test_a_transitive_registry_edge_nested_and_static_imports_pass(self) -> None:
|
||||
text = self.nudge("src/adapter/inbound/web", "dev/caskeleton/adapter/inbound/web/order/OrderController.java",
|
||||
"import dev.caskeleton.application.order.PlaceOrderUseCase;\n"
|
||||
"import dev.caskeleton.domain.order.Order.Line;\n"
|
||||
"import static dev.caskeleton.shared.error.ApiErrorCode.of;\n"
|
||||
"import dev.caskeleton.domain.order.*;\n"
|
||||
"import org.springframework.web.bind.annotation.RestController;")
|
||||
self.assertEqual(text, "")
|
||||
|
||||
def test_test_sources_and_files_outside_any_leaf_are_not_checked(self) -> None:
|
||||
path = "src/domain-core/src/test/java/dev/caskeleton/domain/order/OrderTest.java"
|
||||
self.repo.write(path, "package dev.caskeleton.domain.order;\nimport org.springframework.util.Assert;\nclass OrderTest {}\n")
|
||||
self.assertEqual(hooks.boundary_findings(self.repo.root, path, (self.repo.root / path).read_text()), [])
|
||||
self.assertEqual(hooks.boundary_findings(self.repo.root, "src/other/src/main/java/A.java", "import org.springframework.X;"), [])
|
||||
|
||||
|
||||
class DocumentNudgeTest(RepositoryTestCase):
|
||||
"""N2 — a document edit runs the two document checks and passes on their failure lines."""
|
||||
|
||||
def checks(self, work_docs_failures: list[str], docs_failures: list[str]) -> None:
|
||||
for name, failures in (("check-work-docs.py", work_docs_failures), ("check-docs.py", docs_failures)):
|
||||
body = "import sys\n" + "".join(f"print({' ' + line!r}, file=sys.stderr)\n" for line in failures)
|
||||
body += "sys.exit(1)\n" if failures else ""
|
||||
self.repo.write(f"scripts/{name}", body)
|
||||
|
||||
def test_failures_naming_the_edited_document_come_back(self) -> None:
|
||||
self.checks(["docs/guide.md:3: broken relative link 'x.md'", "docs/other.md:1: history ID"],
|
||||
["[link] docs/guide.md:3: 없는 곳을 가리키는 상대 링크다: x.md"])
|
||||
self.repo.write("docs/guide.md", "# 안내\n")
|
||||
code, out, _ = run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment)
|
||||
text = added_context(out)
|
||||
self.assertEqual(code, 0)
|
||||
self.assertIn("문서 검사 알림(N2) docs/guide.md", text)
|
||||
self.assertIn("broken relative link 'x.md'", text)
|
||||
self.assertIn("없는 곳을 가리키는 상대 링크다", text)
|
||||
self.assertNotIn("docs/other.md", text)
|
||||
self.assertNotIn("print(", text)
|
||||
|
||||
def test_failures_elsewhere_are_shown_when_none_names_the_document(self) -> None:
|
||||
self.checks(["AGENTS.md: 41 lines, limit 40"], [])
|
||||
self.repo.write("docs/guide.md", "# 안내\n")
|
||||
text = added_context(run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment)[1])
|
||||
self.assertIn("AGENTS.md: 41 lines, limit 40", text)
|
||||
|
||||
def test_passing_checks_add_nothing(self) -> None:
|
||||
self.checks([], [])
|
||||
self.repo.write("docs/guide.md", "# 안내\n")
|
||||
self.assertEqual(run_event("post-edit", self.repo.payload("docs/guide.md"), self.environment), (0, "", ""))
|
||||
|
||||
|
||||
class TurnEndNudgeTest(RepositoryTestCase):
|
||||
"""N5 — Java edited and no desktop Gradle run since: the turn end says so once."""
|
||||
|
||||
SOURCE = "src/domain-core/src/main/java/dev/caskeleton/domain/order/Order.java"
|
||||
|
||||
def edit_java(self) -> None:
|
||||
run_event("post-edit", self.repo.payload(self.SOURCE), self.environment)
|
||||
|
||||
def stop(self, **extra) -> dict | None:
|
||||
out = run_event("stop", {"session_id": "s1", "cwd": str(self.repo.root), **extra})[1]
|
||||
return json.loads(out) if out else None
|
||||
|
||||
def bash(self, command: str) -> None:
|
||||
run_event("post-bash", {"session_id": "s1", "cwd": str(self.repo.root), "tool_name": "Bash",
|
||||
"tool_input": {"command": command}})
|
||||
|
||||
def test_a_java_edit_blocks_the_turn_end_once_with_the_reason(self) -> None:
|
||||
self.edit_java()
|
||||
first = self.stop()
|
||||
self.assertEqual(first["decision"], "block")
|
||||
self.assertIn(f"Java 파일 1개를 고쳤고(`{self.SOURCE}`)", first["reason"])
|
||||
self.assertIn("HARD-STOP 6", first["reason"])
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
def test_a_desktop_gradle_run_clears_the_pending_edits(self) -> None:
|
||||
self.edit_java()
|
||||
self.bash("ssh -o BatchMode=yes desktop 'cd ~/w && flock /tmp/claude-gates/heavy.lock ./gradlew :domain-core:check'")
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
def test_a_laptop_command_or_another_host_does_not_count(self) -> None:
|
||||
self.edit_java()
|
||||
self.bash("git log --oneline -1 && echo gradlew")
|
||||
self.bash("ssh buildbox ./gradlew check")
|
||||
self.assertEqual(self.stop()["decision"], "block")
|
||||
|
||||
def test_a_new_java_edit_after_the_reminder_reminds_again(self) -> None:
|
||||
self.edit_java()
|
||||
self.stop()
|
||||
self.edit_java()
|
||||
self.assertEqual(self.stop()["decision"], "block")
|
||||
|
||||
def test_an_active_stop_hook_never_blocks_again(self) -> None:
|
||||
self.edit_java()
|
||||
self.assertIsNone(self.stop(stop_hook_active=True))
|
||||
|
||||
def test_no_java_edit_no_reminder(self) -> None:
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
|
||||
class SettingsWiringTest(unittest.TestCase):
|
||||
"""The committed project settings call these hooks on the events they are written for."""
|
||||
|
||||
def setUp(self) -> None:
|
||||
self.settings = json.loads((REPO / ".claude/settings.json").read_text(encoding="utf-8"))
|
||||
|
||||
def commands(self, event: str, matcher: str | None) -> list[str]:
|
||||
groups = [group for group in self.settings["hooks"][event] if group.get("matcher") == matcher]
|
||||
return [hook["command"] for group in groups for hook in group["hooks"]]
|
||||
|
||||
def test_every_event_calls_its_hook(self) -> None:
|
||||
script = 'python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py'
|
||||
self.assertEqual(self.commands("PreToolUse", "Edit|Write|MultiEdit"), [f"{script} pre-edit"])
|
||||
self.assertEqual(self.commands("PostToolUse", "Edit|Write|MultiEdit"), [f"{script} post-edit"])
|
||||
self.assertEqual(self.commands("PostToolUse", "Bash"), [f"{script} post-bash"])
|
||||
self.assertEqual(self.commands("Stop", None), [f"{script} stop"])
|
||||
|
||||
def test_real_env_files_are_denied_and_the_examples_are_not(self) -> None:
|
||||
deny = self.settings["permissions"]["deny"]
|
||||
for name in (".env", ".env.local", ".env.lane"):
|
||||
self.assertIn(f"Read(**/{name})", deny)
|
||||
self.assertIn(f"Edit(**/{name})", deny)
|
||||
self.assertFalse([rule for rule in deny if "example" in rule or rule.endswith(".env.*)")])
|
||||
|
||||
def test_the_hook_script_runs_from_the_command_line(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as project:
|
||||
result = subprocess.run([sys.executable, str(SCRIPTS / "hooks/hooks.py"), "stop"], input="{}",
|
||||
capture_output=True, text=True, cwd=project,
|
||||
env={**os.environ, "CLAUDE_PROJECT_DIR": project})
|
||||
self.assertEqual((result.returncode, result.stdout), (0, ""))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,53 @@
|
||||
"""docs/ledger/estimates.jsonl의 줄이 docs/ledger/README.md 형식인지 본다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import unittest
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
|
||||
REPO = Path(__file__).resolve().parent.parent.parent
|
||||
LEDGER = REPO / "docs/ledger/estimates.jsonl"
|
||||
KINDS = {"estimate", "actual", "retro"}
|
||||
COMMON = ("schema", "kind", "task", "recorded_at")
|
||||
RANGES = ("minutes", "calls", "output_tokens")
|
||||
|
||||
|
||||
def lines() -> list[dict]:
|
||||
return [json.loads(line) for line in LEDGER.read_text(encoding="utf-8").splitlines() if line.strip()]
|
||||
|
||||
|
||||
class LedgerTest(unittest.TestCase):
|
||||
def test_every_line_is_json_with_the_common_fields(self) -> None:
|
||||
for number, entry in enumerate(lines(), start=1):
|
||||
self.assertTrue(set(COMMON) <= entry.keys(), f"line {number}: {sorted(set(COMMON) - entry.keys())}")
|
||||
self.assertEqual(entry["schema"], 1, number)
|
||||
self.assertIn(entry["kind"], KINDS, number)
|
||||
datetime.fromisoformat(entry["recorded_at"])
|
||||
|
||||
def test_an_estimate_has_ordered_ranges_and_a_basis(self) -> None:
|
||||
for entry in (e for e in lines() if e["kind"] == "estimate"):
|
||||
for field in RANGES:
|
||||
values = entry[field]
|
||||
self.assertLessEqual(values["p30"], values["p50"], (entry["task"], field))
|
||||
self.assertLessEqual(values["p50"], values["p80"], (entry["task"], field))
|
||||
self.assertTrue(entry["basis"].strip(), entry["task"])
|
||||
|
||||
def test_an_actual_follows_its_estimate_and_names_the_band_it_fell_in(self) -> None:
|
||||
entries = lines()
|
||||
for position, entry in enumerate(entries):
|
||||
if entry["kind"] != "actual":
|
||||
continue
|
||||
estimates = [e for e in entries[:position] if e["kind"] == "estimate" and e["task"] == entry["task"]]
|
||||
self.assertTrue(estimates, f"{entry['task']}: an actual line needs an earlier estimate line")
|
||||
bands = estimates[-1]["minutes"]
|
||||
expected = next((band for band in ("p30", "p50", "p80") if entry["active_minutes"] <= bands[band]), "over")
|
||||
self.assertEqual(entry["within"], expected, entry["task"])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,47 +0,0 @@
|
||||
{
|
||||
"version": 1,
|
||||
"skills": {
|
||||
"cavecrew": {
|
||||
"source": "JuliusBrussee/caveman",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/cavecrew/SKILL.md",
|
||||
"computedHash": "505d836228d1c5e14834ff5d62aad72390c7d27f79c6aa7f9a7a55ed6606d6a2"
|
||||
},
|
||||
"caveman": {
|
||||
"source": "JuliusBrussee/caveman",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/caveman/SKILL.md",
|
||||
"computedHash": "1902fa0b569912d0c05736d8d98a72097d9b82719aac88c0c1d03bb546f9176d"
|
||||
},
|
||||
"caveman-commit": {
|
||||
"source": "JuliusBrussee/caveman",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/caveman-commit/SKILL.md",
|
||||
"computedHash": "790a4eeace0be35c6691faf923518ba5bd50f1f1305d1101d09dd4971be94e00"
|
||||
},
|
||||
"caveman-compress": {
|
||||
"source": "JuliusBrussee/caveman",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/caveman-compress/SKILL.md",
|
||||
"computedHash": "1e9b3e2bf68b75dc0252c4328c8514bea79d4d8f7d7259da616ba7d12cad6865"
|
||||
},
|
||||
"caveman-help": {
|
||||
"source": "JuliusBrussee/caveman",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/caveman-help/SKILL.md",
|
||||
"computedHash": "dd85267e76baad76995157e7b9f762dfa557cd58951ee92af0c283f48aa26537"
|
||||
},
|
||||
"caveman-review": {
|
||||
"source": "JuliusBrussee/caveman",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/caveman-review/SKILL.md",
|
||||
"computedHash": "fb7214a1c5793bae6ba8b1be4329e2e6f40dbec6dd911dfb335ad29f09c316a1"
|
||||
},
|
||||
"caveman-stats": {
|
||||
"source": "JuliusBrussee/caveman",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/caveman-stats/SKILL.md",
|
||||
"computedHash": "47ce2de3d6cb39a75047b5c962e4eb3da15594e7397c94103e9a104d42626553"
|
||||
}
|
||||
}
|
||||
}
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
# src — 빌드 스크립트 / 환경 변수 참조
|
||||
|
||||
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
|
||||
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT이다.
|
||||
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [AGENTS.md](../AGENTS.md),
|
||||
모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다.
|
||||
|
||||
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
|
||||
결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# adapter:inbound:* — inbound adapter family 공통 규칙
|
||||
|
||||
모든 inbound leaf에 같은 규칙만 적는다. leaf마다 자기 폴더의 `AGENTS.md`가 그 leaf의 자세한 규칙(등록 정보, 허용·금지, 테스트 명령)을 둔다. 루트 `AGENTS.md` HARD-STOP이 이 문서와 leaf 문서보다 먼저다.
|
||||
|
||||
## 책임
|
||||
|
||||
- HTTP·gRPC·GraphQL·WebSocket·메시지 수신 같은 transport, 요청·응답 DTO, 입력 검증, 인증·인가 매핑, 오류 매핑.
|
||||
- 요청 DTO를 `application-core`의 command·query로 바꿔 유스케이스를 부른다. 엔드포인트는 얇게 둔다.
|
||||
|
||||
## 금지
|
||||
|
||||
- repository·Spring Data interface·persistence entity를 직접 쓴다(HARD-STOP 2).
|
||||
- inbound DTO를 `application-core`·`domain-core`로 넘긴다(HARD-STOP 3).
|
||||
- 업무 정책을 controller·mapper·filter에 둔다(HARD-STOP 4).
|
||||
- registry `allowed_dependencies`에 없는 leaf에 기댄다(HARD-STOP 5).
|
||||
|
||||
## 테스트
|
||||
|
||||
- transport 검증, 인증·인가 매핑, 상태 코드와 응답 계약을 검증한다.
|
||||
- 작성 규칙은 `.claude/rules/java-tests.md`다.
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user