From 63c63413d19c8a80ab433fdbebd1f031a6399caa Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 19:58:44 +0900 Subject: [PATCH] =?UTF-8?q?docs(work):=20=EC=A7=80=EB=8F=84=EC=99=80=20?= =?UTF-8?q?=EC=9E=91=EC=97=85=20=EC=A2=85=EB=A5=98=EB=B3=84=20playbook?= =?UTF-8?q?=EC=9C=BC=EB=A1=9C=20=EC=9E=91=EC=97=85=20=EB=A7=A4=EB=89=B4?= =?UTF-8?q?=EC=96=BC=EC=9D=84=20=EB=A7=8C=EB=93=A0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와 리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이 "이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는 없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지), 커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음). 고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs delegation-loop/02-design.md 4~6·10절): - CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본 AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는 곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던 내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은 reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절. - docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개 (new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns, decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고 review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에 나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고, improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다. - improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과 수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난 수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25, +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다. - 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를 README 4절과 AGENTS.md에 같은 말로 적었다. - 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인 (reference/decisions.md, reference/defect-patterns.md)에만 둔다. - 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md, docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운 CLAUDE.md 「Layer workflow」를 가리키던 줄). 위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라 초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어 docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/ 본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의 성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다. 검증 - python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80, playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄 - python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0 - CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest .guidanceNamesTheArchitectureSourceSetTask가 기대하는 "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는 이 커밋을 push한 뒤 desktop에서 돌린다 --- AGENTS.md | 9 +- CLAUDE.md | 207 +++++------------- README.md | 5 +- docs/README.md | 3 +- docs/manual/02-new-feature.md | 4 +- docs/manual/README.md | 5 +- docs/work/README.md | 75 +++++++ docs/work/delegate.md | 116 ++++++++++ docs/work/docs-writing.md | 83 ++++++++ docs/work/evidence.md | 150 +++++++++++++ docs/work/improve.md | 132 ++++++++++++ docs/work/new-feature.md | 79 +++++++ docs/work/operate.md | 115 ++++++++++ docs/work/reference/decisions.md | 188 ++++++++++++++++ docs/work/reference/defect-patterns.md | 131 ++++++++++++ docs/work/reference/gates.md | 129 +++++++++++ docs/work/reference/review-criteria.md | 283 +++++++++++++++++++++++++ docs/work/research-design.md | 90 ++++++++ 18 files changed, 1636 insertions(+), 168 deletions(-) create mode 100644 docs/work/README.md create mode 100644 docs/work/delegate.md create mode 100644 docs/work/docs-writing.md create mode 100644 docs/work/evidence.md create mode 100644 docs/work/improve.md create mode 100644 docs/work/new-feature.md create mode 100644 docs/work/operate.md create mode 100644 docs/work/reference/decisions.md create mode 100644 docs/work/reference/defect-patterns.md create mode 100644 docs/work/reference/gates.md create mode 100644 docs/work/reference/review-criteria.md create mode 100644 docs/work/research-design.md diff --git a/AGENTS.md b/AGENTS.md index 3341d675..b5c1d5a7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,8 +22,9 @@ 6. 관련 검증 없이, 또는 실행하지 못한 이유를 밝히지 않고 완료를 주장한다. 7. 결론의 범위와 위험에 맞는 증거 없이 repository/corpus 전체 결론을 내린다. -root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어긋나면 이 `AGENTS.md` 목록이 -우선한다. 자동 강제 범위는 아래 Gradle 정책 권위와 ArchUnit/Test가 담당한다. +root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 한 줄씩 가리킨다. 두 문서가 어긋나면 +이 `AGENTS.md` 목록이 우선한다. 일의 종류별 절차는 `docs/work/`에 있다. 자동 강제 범위는 아래 Gradle +정책 권위와 ArchUnit/Test가 담당한다. ## Superpowers Workflow @@ -37,7 +38,7 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어 - `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`: 버그, 실패한 테스트, 예상 밖 동작을 다룰 때 사용한다. @@ -107,6 +108,8 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어 변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다. commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다. +예외는 하나다: 작업 지시(brief)가 허용하면 그 작업의 자기 브랜치에만 commit·push한다. main 병합, +다른 브랜치 push, force push는 하지 않는다(`docs/work/README.md` 「커밋」). ## 강제 수준 diff --git a/CLAUDE.md b/CLAUDE.md index 4921a632..2bcb271e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,136 +1,45 @@ -# CLAUDE.md +# CLAUDE.md — 이 repo의 지도 -Repository guidance for the Java 21 + Spring Boot 4.0.8 Clean Architecture template. +이 파일은 세션이 처음 읽는 지도다. 규칙을 담지 않고, 어떤 일이면 무엇을 읽을지 가리킨다. -## Prime Directive +## 1. 이 repo -Preserve architecture before optimizing for speed. The following seven HARD-STOP conditions are a -synchronized summary of the canonical local policy in `AGENTS.md`: +- Java 21 + Spring Boot 4.0.8 Gradle 멀티모듈 Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다. +- Gradle 루트는 `src/`다. Gradle 명령은 `src/`에서 실행한다. +- 규칙의 정본은 `AGENTS.md`다. leaf 목록·경로·허용 의존의 정본은 `src/config/architecture/modules.json`(registry)이다. 각 leaf의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`가 정한다. -1. `domain-core` gains framework, transport, database, or cloud dependencies. -2. A controller directly uses a repository, Spring Data interface, or persistence entity. -3. An inbound DTO leaks into `application-core` or `domain-core`. -4. Business rules move into mappers, filters, configuration, settings, or controllers. -5. Project dependencies violate `src/config/architecture/modules.json` or the Gradle dependency - gate. -6. Completion is claimed without the relevant verification or a named reason it could not run. -7. A repository/corpus conclusion is made without evidence proportional to its scope and risk. +## 2. HARD-STOP — 하나라도 어기면 완료가 아니다 -If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must be resynchronized. +정본은 `AGENTS.md` 「Prime Directive」다. 두 문서가 다르면 `AGENTS.md`가 맞다. -## Gradle policy authorities +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. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다. -- `src/config/architecture/modules.json`: every registered leaf identity, repository-relative source - paths, Gradle paths and allowed production project dependency edges. There is no runtime - membership list: what a composition root may take is its `allowed_dependencies`, and the direction - gate refuses any other edge. The registry owns the leaf list and its size; no document restates - the count, because a number written in prose drifts the moment a leaf is added. -- `src/settings.gradle`: fail-closed registry validation, project inclusion, and directory mapping. -- `src/build-logic/`: the architecture core (registry, direction and purity tasks), the conventions, - and one test-lane mechanism (`strictTestLanes`). Feature-specific checks are the owning leaf's - tests; a test that reads repository files declares them as that leaf's test `inputs`, and a test - that compares a leaf with repository documents is a `mainStage()` lane (tag `document-contract`) - in that leaf's `mainCheck`; a merge-blocking contract over non-document repository files is a - pull-request lane whose inputs are exactly those files (app-bootstrap `repository-contract`). - `TEST`/`ARCHITECTURE` lanes are cacheable; `INTEGRATION`/`SYSTEM`/`PERFORMANCE` and main-stage - lanes rerun every time. -- `verifyEnvKeys` stays an app-bootstrap task (owner decision 4); its implementation is build-logic's - `ca.config-contract`. The `src/build-tools/` included build was emptied and removed. -- `src/build.gradle`: the root lifecycle (`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, - `releaseCheck` and the named repository-wide gates). `verifyStrictLaneStages --dry-run` (pull - request; the main build and, as `-p optional-platforms`, the optional build each run their own) - fails when a non-`explicitOnly` strict lane is in no stage a workflow executes — a lane the - command removes with `-x` (abbreviations matched as Gradle does) is not covered; a command after - which Gradle runs no task (`--dry-run`, `-v`, `--help`, `--status`, `--stop`, …, bundles such as - `-qm` included), a short-option bundle Gradle rejects (`-mx`) and a command for another build do - not count, nor does one that does not gate for one of three reasons: (1) its failure may not fail - its step (an `||` other than `|| exit `, a pipe without pipefail, an `if` condition, - after `set +e` or an `exit 0` trap, `continue-on-error`, …); (2) it may not run (inside - `if`/`for`/`case` or a function, after a top-level or conditional `exit 0`, `exec` or `set -n`, - under a non-status `if:`, in a workflow only a request starts or a `workflow_call` one no counted - job calls, in a job that `needs` a conditional job, …); (3) the check does not read it although - its failure would fail the step (`|| exit 1`, inside `{ }`, `( )`, `$( )` or `bash -c`, after a - `cd` it cannot follow, a `shell:` other than bash or sh, a runner that may be Windows with its - `pwsh` default, …) — the failure names each command's reason and says to put the stage command - on a line of its own; the build a command runs is its `working-directory`, then the - `cd ` the same shell surely ran before it, joined with `-p` — or a folded workflow - `run:` block splits an option off its command. +## 3. 맡은 일 → 읽을 문서 -Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes. +먼저 [docs/work/README.md](docs/work/README.md)를 읽는다. 크기 정하기, 모든 작업의 공통 단계, 커밋 규칙이 거기 있다. 그다음 맡은 일의 playbook 하나를 끝까지 읽는다. -## Proportional workflow +| 맡은 일 | 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) | -- Low risk: work in the owning leaf, follow its nearest guidance, and run the focused check. -- Medium risk: use the relevant Superpowers design, planning, TDD, debugging, and review workflows - in proportion to the affected boundaries. -- High risk: make architecture and behavior decisions explicit, use staged architecture/spec/quality - review, and run architecture-wide verification authorized by the task. +brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 먼저다. playbook은 brief에 없는 공통 절차를 채운다. -Risk comes from change surface and runtime, security, data, or public-contract impact, not file -count. +## 4. 검증 명령과 실행 위치 -## Module families - -`src/config/architecture/modules.json` owns the complete leaf list. Root guidance summarizes -families; the nearest `src/**/CLAUDE.md` owns local rules. No task enforces this any more: -`verifyDocumentedLeafCount` was deleted along with the other documentation-drift parsers. A stated -count that disagrees with the registry is a defect, not a build failure — so do not state one. - -| Family | Responsibility | Stable dependency direction | -| --- | --- | --- | -| `domain-core` | Pure domain model, invariants, events, ports | Java stdlib and registered value-only contracts | -| `application-core` | Commands, use cases, application policies, transaction ports | `domain-core`, `shared-contract` | -| `adapter:inbound:*` | HTTP, gRPC, GraphQL, WebSocket transport boundaries | application/domain/shared contracts | -| `adapter:outbound:persistence-*` | JPA/PostgreSQL and MongoDB persistence adapters | application/domain/shared contracts as registered | -| `adapter:outbound:*` | support, messaging, cache, notification, storage, file, HTTP client, identifier capabilities | application/domain/shared and registered support edge | -| `shared-contract` | Skeleton-wide operational contracts | Java stdlib only | -| `messaging:*` | Vendored messaging platform: a product with its own API, SPI, adapters and composition boundary, not a layer of this application | `messaging:*` only — it depends on no `domain-core`, `application-core`, or `shared-contract` type | -| `sample-portfolio` | Fixture/reference consumer | registered runtime leaves; never a production dependency | -| `app-bootstrap` | Spring Boot entrypoint and composition root | registered runtime leaves | - -The `messaging:*` family is the one entry that is not a Clean Architecture layer, and it is listed so -that the exception is stated rather than inferred from a directory. It is a vendored library — its -own `*-api` leaves are its ports, its broker leaves are its adapters, its starter is its composition -root — and the messaging module review (`docs/reviews/2026-08-14-messaging-module-code-review.md` -MSG-023 §6.2) chose that layout deliberately over folding it into `adapter:outbound:*`. This -application reaches it through the application-owned anti-corruption bridge in -`adapter:outbound:messaging` (MSG-015). The canonical bridge is the only path: the legacy outbox -append port and the legacy Kafka publishing seam were deleted (owner decision 7). - -Never infer an individual leaf's Gradle path, allowed dependency, or test command from this table. -Read its `gradle_path` and `allowed_dependencies` from `src/config/architecture/modules.json`; runtime -composition is established by actual Gradle dependencies/auto-configuration, not a registry -`runtime_memberships` field that does not exist. - -## Layer workflow - -For a full use case, work in this order: - -```text -domain-core - -> application-core - -> adapter:outbound:* (or persistence/identifier) - -> adapter:inbound:* - -> app-bootstrap wiring -``` - -Layer-only work stays inside that registered leaf plus its tests. If a required fix crosses a layer -or writable scope, stop and request context rather than expanding silently. - -## Testing - -- `domain-core`: pure JUnit unit tests. -- `application-core`: use-case tests with hand-rolled fakes; no web or persistence context. -- inbound adapters: focused transport slice/contract tests. -- persistence adapters: mapping/port contract tests; use a real datastore only when vendor semantics - require it. -- other outbound adapters: port contract tests with fake external systems; no real network. -- identifier: pure deterministic unit tests. -- bootstrap/settings: binding, validation, wiring, and architecture tests. - -From `src/`, read the owning leaf's `gradle_path` from -`config/architecture/modules.json` and run `./gradlew :test --console=plain`. -Architecture-wide commands: +- **실행 위치**: Gradle·Docker·테스트·게이트는 이 repo 소유자 환경에서 desktop에서만 돌린다. 절차는 [docs/work/operate.md](docs/work/operate.md) 4.1절이다. +- **leaf 하나**: registry에서 그 leaf의 `gradle_path`를 읽고 `./gradlew :test --console=plain` 또는 `:check`를 돌린다. 기억이나 디렉터리 이름으로 Gradle path를 짐작하지 않는다. +- **저장소 전체 질문**: ```bash ./gradlew architectureCheck --console=plain @@ -139,45 +48,25 @@ Architecture-wide commands: ./gradlew :app-bootstrap:verifyEnvKeys --console=plain ``` -A leaf's `check` covers that leaf only — compile, its tests, Spotless, Checkstyle, Error Prone. -Repository-wide questions have their own names: `architectureCheck` (dependency direction, purity -of domain-core/shared-contract/application-*, Git-carryable sources, ArchUnit), `qualityCheck` -(SpotBugs, FindSecBugs over production code), `testQualityCheck` (the same over every test source -set, against `config/spotbugs/exclude-test.xml`), `configContractCheck` (the environment contract), `integrationCheck` (the -declared strict integration lanes; a lane that needs an input the build was not given is left out -and named), `performanceCheck` (the declared performance lanes; main and nightly). `ci` (pull -request) is leaf checks (API surfaces included, owner decision 20) + architectureCheck + -qualityCheck, and the workflow also runs `verifyStrictLaneStages --dry-run`; `mainCheck` (main branch) is configContractCheck + -qualificationCheck (which includes testQualityCheck) + the sample web contract + the sample full boot (`:sample-portfolio:systemTest`) -+ the public-path snapshot + the transport and messaging qualification lanes + the feature -generator round trip (`verifyFeatureScaffold`) + every leaf's `mainCheck` (document-contract lanes -and any lane the leaf adds). `releaseCheck` is the tag-only checks: release provenance and the -public-path snapshot. +- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다. +- 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다. +- `docs/work/`나 이 파일을 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다. -Test-writing rules (behavior-sentence names that assert what they promise, `@DisplayName` in Korean -only when the name cannot say it (owner decision 5), given/when/then comments, one `// when`, one -fake per port in the port owner's testFixtures, fake and adapter sharing one abstract contract test) -are canonical in `AGENTS.md`. +## 5. 코드만 보고는 헷갈리는 곳 -Use public-path and env-key checks only when their surfaces changed. Full `test`, `check` or `ci` -requires the controller's workflow authorization. +- **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. +- **`src/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/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/grpc/*`·`src/grpc-advanced/*`(registry의 `"build": "optional-grpc"`)는 `-p optional-platforms`로 돈다. `adapter:inbound:grpc`는 애플리케이션 adapter라 주 빌드에 있다. +- **`src/sample-portfolio`는 지울 수 있는 샘플이다.** 한 leaf에 모든 계층을 둔 모양이라 배치를 따라 하지 않는다. 새 기능의 예시는 `scripts/new-feature.sh`의 출력이다. +- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `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/superpowers/specs/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다. -## Capability modules +## 6. 소유자 환경 -Optional features (JPA, Redis, Kafka, notification, Mongo, object storage, HTTP client, GraphQL, -WebSocket, gRPC, file server) are modules that turn on when present and disappear when removed. A -service selects them with one `runtimeOnly` line each in `app-bootstrap/build.gradle`; the template's -default composition is the web inbound adapter, observability, the cores, and support/identifier. The -seven completion criteria for a capability module are canonical in `AGENTS.md`. - -## Advisory and reporting - -Use dependency-DAG/topological reasoning and 3–5 materially distinct alternatives when that many -exist; use fewer when the option set is smaller. Judgment findings include falsifiable assumptions -and counterarguments. Deterministic compile, dependency, secret, or failed-test findings use -Rule → Evidence → Fix without manufactured debate. - -Citation verification is profile-based: none for `review-lite`, blocking citations for -`review-standard`, and all material citations for `audit-deep`/`regulated`. Durable reports are -triggered by high risk, at least 3 blocking findings, an architecture decision, explicit user request, -or the regulated profile. Otherwise a concise result is allowed. +- 이 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`를 따른다. diff --git a/README.md b/README.md index d114e00a..3d6b69a0 100644 --- a/README.md +++ b/README.md @@ -112,8 +112,9 @@ cd src ## 아키텍처 규칙과 검증 -애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. 8개 HARD-STOP 조건의 정본 로컬 -정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 동기화된 요약입니다. +애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬 +정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 작업을 시작할 때 읽는 지도입니다. +일의 종류별 절차는 [docs/work/](docs/work/README.md)에 있습니다. - `domain-core`는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다. - controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다. diff --git a/docs/README.md b/docs/README.md index 4d745431..eb2e413c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,7 +24,8 @@ | --- | --- | | `adr/` | 아키텍처 결정 기록 | | `architecture/` | 공개 API 표면 스냅숏 | -| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`) | +| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 | +| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` | | `evidence/` | 작업 단계별 증거·체크포인트 | | `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT | | `reviews/` | 모듈 코드 리뷰 결과 | diff --git a/docs/manual/02-new-feature.md b/docs/manual/02-new-feature.md index 8bdf7814..d4902048 100644 --- a/docs/manual/02-new-feature.md +++ b/docs/manual/02-new-feature.md @@ -12,8 +12,8 @@ ``` 바깥 계층은 안쪽을 알지만 안쪽은 바깥을 모른다. 그래서 안쪽부터 만들면 각 단계가 앞 단계만 보고 -컴파일된다. 한 단계가 다른 leaf나 계층을 고쳐야 하면 거기서 멈추고 설계를 다시 본다(`CLAUDE.md` -Layer workflow). +컴파일된다. 한 단계가 다른 leaf나 계층을 고쳐야 하면 거기서 멈추고 설계를 다시 본다 +([새 기능 playbook](../work/new-feature.md) 「하지 말 것」). ## 0단계 — 배치를 정한다 diff --git a/docs/manual/README.md b/docs/manual/README.md index d5216db7..8ad6ff24 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -4,6 +4,9 @@ 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 **가리키고** 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」). +입구는 작업 매뉴얼의 [새 기능 playbook](../work/new-feature.md)이다. 일의 크기, 완료 기준, 하지 말 것은 +거기에 있다. 새 기능이 아닌 일(개선, 조사·설계, 문서, 운영)은 [docs/work/](../work/README.md)가 맡는다. + 판단 지점은 모두 같은 틀로 적는다. - **고르는 기준** — 무엇을 보고 고르는가 @@ -37,7 +40,7 @@ | 무엇 | 정본 | | --- | --- | -| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(요약은 `CLAUDE.md`) | +| 계층 경계·금지 규칙·테스트 작성 규칙 | `AGENTS.md`(작업 지도는 `CLAUDE.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」 | diff --git a/docs/work/README.md b/docs/work/README.md new file mode 100644 index 00000000..3926c8a7 --- /dev/null +++ b/docs/work/README.md @@ -0,0 +1,75 @@ +# 작업 매뉴얼 + +이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다. +읽는 순서는 하나다: 루트 `CLAUDE.md`(지도) → 이 README → 맡은 일의 playbook 하나. +규칙의 정본은 `AGENTS.md`와 registry(`src/config/architecture/modules.json`)다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다. + +## 1. 어떤 playbook인가 + +| 맡은 일 | playbook | +| --- | --- | +| 새 업무 기능이나 새 capability 모듈을 만든다 | [new-feature.md](new-feature.md) | +| 있는 코드를 리뷰·수정·리팩터링·최적화한다. 구조·테스트 구조를 바꾼다 | [improve.md](improve.md) | +| 바꾸기 전에 대안을 비교하고 소유자 결정을 받는다 | [research-design.md](research-design.md) | +| 매뉴얼·안내 문서를 쓰거나 고친다 | [docs-writing.md](docs-writing.md) | +| 게이트를 돌린다, 릴리스한다, 파생 서비스에 템플릿 변경을 넘긴다 | [operate.md](operate.md) | +| 큰 일을 나눠 다른 세션에 맡긴다 | [delegate.md](delegate.md) | + +둘에 걸리면 이렇게 고른다. 결정이 먼저 필요하면 research-design이다. 동작이 바뀌는 코드가 있으면 new-feature나 improve다. 문서만 바뀌면 docs-writing이다. + +## 2. 크기 정하기 + +- 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs `conventions/work-thinking-order.md` 2절이 정본이다. +- 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 leaf(또는 문서 폴더) 하나 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다. +- brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다. +- brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다. +- 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다. +- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 `docs/web/http-contract.md`, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 보안 정책. +- 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다([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에 작업별 스킬이 있다. +5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. +6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다. +7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절). +8. 완료를 말하기 전에 검증한다(`superpowers:verification-before-completion`). 돌리지 못한 검증은 못 돌렸다고, 이유와 함께 쓴다(HARD-STOP 6). + +## 4. 커밋 + +- 기본 정책은 `human-only`다(`AGENTS.md`). 에이전트는 stage·commit·amend·push하지 않는다. +- 예외는 하나다. brief가 커밋을 허용하면, 그 작업의 자기 브랜치에만 커밋하고 push한다. +- 그때도 main 병합, 다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자가 한다. +- 메시지 형식은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말과 자리표시자(`TBD`, `TODO`, 채우지 않은 칸)를 넣지 않는다. + +## 5. 막혔을 때 + +- 소유자만 정할 수 있는 것(공개 계약, 파생 서비스 동작, 보안 정책, 새 leaf, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다. +- brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다. +- 묻는 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람. + +## 6. 보고 + +- 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다. +- 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다. +- 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다. +- 사고 순서 흔적 칸을 둔다(`conventions/work-thinking-order.md` 3절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다. + +## 7. 필요할 때만 읽는 문서 + +| 문서 | 내용 | +| --- | --- | +| [reference/gates.md](reference/gates.md) | 게이트 목록, 바꾼 것에 맞는 게이트, 결과 기록 형식, 거짓 통과 막기 | +| [reference/review-criteria.md](reference/review-criteria.md) | 결함 정의, 심각도, 증거·통제 수준, 점검 항목, 리뷰 문서 양식 | +| [reference/defect-patterns.md](reference/defect-patterns.md) | 반복해서 나온 결함의 모양과 막는 기준 | +| [reference/decisions.md](reference/decisions.md) | 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법 | +| [evidence.md](evidence.md) | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID | + +## 8. 이 폴더를 고칠 때 + +- 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄. `reference/`는 상한이 없다. +- 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. +- 고친 뒤 `python3 scripts/check-work-docs.py`가 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다. diff --git a/docs/work/delegate.md b/docs/work/delegate.md new file mode 100644 index 00000000..5e8a49f9 --- /dev/null +++ b/docs/work/delegate.md @@ -0,0 +1,116 @@ +# 총괄 — 큰 일을 나눠 다른 세션에 맡긴다 + +총괄 세션이 일을 나누고, brief를 쓰고, 결과를 대조하고, 합치는 절차다. 공용 절차(brief 양식, 보고 양식, 대조, 교훈 정리, 장부, 지표, cold-read 시험)의 정본은 design-docs `conventions/delegation-loop.md`다. 이 playbook은 그것을 다시 쓰지 않고, 이 repo의 일을 나누는 법만 더한다. + +## 1. 언제 쓰나 + +- 일이 커서 여러 세션으로 나눠야 할 때: 전체 리뷰, 영역별 수정 묶음, 리뷰와 수정과 확인 리뷰의 반복, 여러 playbook에 걸친 일. +- 세션 하나가 끝까지 할 수 있는 일이면 이 playbook이 아니다. 그 일의 playbook을 쓴다. +- 맡은 쪽(하위 세션)은 이 playbook이 아니라 brief가 가리킨 playbook을 따른다. + +## 2. 받아야 할 것 + +- 소유자의 목표와 이미 정한 결정. 큰 일이면 소유자가 계획을 검토한 시각. +- 결과가 올라갈 브랜치와 그 최신 커밋(기준 커밋). +- 커밋·push 허용 범위. 하위 세션 브랜치 push는 desktop 검증에 필요하다. main 병합·push는 소유자가 한다. +- 마감과 보고 받을 방법. + +## 3. 크기와 사고 순서 + +- 크기는 총괄이 정해 brief에 적는다. 정의는 design-docs `conventions/work-thinking-order.md` 2절이다. +- 큰 일은 하위 세션이 1~5단계와 대안 비교까지만 하고 멈추게 brief를 쓴다. 소유자 검토 뒤 만들기를 다시 맡긴다. +- 총괄 자신의 선행 사례는 지난 라운드의 나누는 법이다: 가장 최근 리뷰 README의 영역 표와 처리 표, [evidence.md](evidence.md) 2절. +- 스킬: `delegate`(소유자 환경의 실행판)가 있으면 쓴다. 정본과 다르면 정본이 맞다. + +## 4. 절차 + +### 4.1 맡기고 닫는 순서 + +design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 → 나누기(4.2절) → 기준 커밋 → brief(그 문서 4절 양식, 60줄 이하) → 하위 세션 띄우기 → 보고 대조(그 문서 6절) → 합치기 → 교훈 정리(그 문서 7절) → 장부 한 줄(그 문서 8절) → 소유자 보고. + +이 repo에서 더할 것: + +- 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절). desktop 검증이 필요하면 7절에 자기 브랜치 push를 허용한다. +- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸부터 보라고 적는다. +- 리뷰 brief에는 쓸 심각도 체계([reference/review-criteria.md](reference/review-criteria.md) 3절)와 "발견마다 이번 수정이 만들었나 / 이전부터"를 요구한다. +- 대조할 때: 보고의 태스크 이름·테스트 수를 desktop 로그에서 grep으로 찾는다. High·Important 이상은 총괄이 코드에서 직접 다시 확인한다. +- 리뷰 결과를 받으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`로 색인이 빠짐없는지 본다. 수정 묶음은 색인에서 배정한다. +- 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 [reference/defect-patterns.md](reference/defect-patterns.md), 거짓 통과는 [reference/gates.md](reference/gates.md) 6절, 근거는 [evidence.md](evidence.md). + +### 4.2 나누는 법 — 이 repo + +영역은 가장 최근 리뷰 README의 영역 표를 다시 쓴다. 없으면 아래를 쓴다. 영역 하나에 하위 세션 하나다. + +| 영역 | 경로 | +| --- | --- | +| core·application | `src/domain-core`, `src/application-*`, `src/shared-contract` | +| inbound 전송 | `src/adapter/inbound/*`, `src/grpc/*`·`src/grpc-advanced/*`(optional 빌드) | +| persistence | `src/adapter/outbound/persistence-*`, 마이그레이션 | +| outbound capability | 그 밖의 `src/adapter/outbound/*`, 멱등성 store | +| messaging | `src/messaging/*`, `src/adapter/outbound/messaging` | +| bootstrap·build·CI | `src/app-bootstrap`, `src/composition/*`, `src/build-logic`, `src/build.gradle`, `.github/` | +| 보안(영역을 가로질러) | 인증·인가 체인, 비밀, 공개 경로 | +| 샘플·문서 | `src/sample-portfolio`, `docs/` | + +두 세션이 동시에 만지면 손으로 풀어야 하는 파일이다. 한 세션만 맡기거나, 총괄이 합칠 때 직접 고친다. + +| 파일 | 왜 | +| --- | --- | +| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹친다 | +| `docs/reviews/<폴더>/README.md` | 처리 표·결정·게이트 기록은 총괄이 쓴다 | +| `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/` | 모든 세션이 읽는다 | +| `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 | + +나눌 때 지킬 것: + +- 두 묶음이 같은 파일을 건드리지 않게 나눈다. +- 묶음마다 그 시점 최신 기준에서 시작한다. +- 묶음 크기 상한을 지킨다([improve.md](improve.md) 4.4절: 영역 하나, 발견 8건 이하, 확인 리뷰당 추가 1,500줄 이하). +- 전 leaf의 import를 바꾸는 묶음은 나머지를 합친 뒤 혼자 마지막에 한다. +- 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. +- 합칠 때는 하위 브랜치를 모아 [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로 우회하지 않는다. +- 실행 위치(desktop, 공유 잠금, desktop worktree)는 [operate.md](operate.md) 4.1절이다. + +## 5. 완료 기준 + +- 하위 세션마다 brief가 양식대로이고 자리표시자가 없다. +- 보고를 diff·커밋·로그와 대조했고 불일치를 셌다. +- 합친 트리에서 라운드 끝 게이트가 통과했다(desktop 로그). +- 리뷰·수정 반복이면 [improve.md](improve.md) 4.5절 멈춤 기준이 모두 참이다. +- 교훈 정리와 장부 한 줄을 끝냈다. +- 소유자 보고에 변경 / 확인(명령·결과·커밋) / 남은 문제가 있다. + +## 6. 하지 말 것 + +- 하위 세션의 일을 대신 하지 않는다. 대조에 필요한 읽기와 확인만 직접 한다. +- 보고를 그대로 믿지 않는다. 보고는 E0 증거다. +- 같은 파일을 두 세션에 맡기지 않는다. +- 하위 세션에 main 병합·push, force push, 다른 브랜치 push를 허용하지 않는다. +- brief에 결정 번호만 쓰지 않는다. 내용을 쓴다. + +## 7. 막혔을 때 + +- 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 소유자에게 한 번 묻는다. 그 결정에 기대는 묶음만 멈추고 나머지는 계속한다. +- 하위 세션이 묻는 질문에는 답하고, 질문 원문과 "답이 매뉴얼에 있었나"를 적어 둔다. 장부의 질문 수가 된다. + +## 8. 보고 형식 + +소유자에게는 변경 / 확인 / 남은 문제 세 칸으로 쓴다. 하위 세션 보고 양식과 대조표는 design-docs `conventions/delegation-loop.md` 5·6절이다. 소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 남은 문제와 섞지 않는다. + +## 9. 자주 하는 실수 + +- 영역 문서의 ID를 색인에 손으로 옮기다 빠뜨린다. 색인 검사 스크립트를 돌린다. +- 묶음을 너무 크게 만들어 마감 안에 검증 보고가 오지 않는다. 묶음 크기 상한을 지킨다. +- 하위 세션이 적은 태스크 이름을 확인하지 않고 소유자에게 옮긴다. diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md new file mode 100644 index 00000000..cd12d358 --- /dev/null +++ b/docs/work/docs-writing.md @@ -0,0 +1,83 @@ +# 문서 작성 — 매뉴얼과 안내 문서를 쓰고 고친다 + +읽은 사람이 묻지 않고 그대로 일할 수 있는 문서를 쓰는 절차다. 매뉴얼은 시험하기 전까지 초안이다. + +## 1. 언제 쓰나 + +- `docs/work/`, `docs/manual/`, 루트·leaf `CLAUDE.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때. +- 이것은 아니다. + - 리뷰 문서 → [improve.md](improve.md)(리뷰 양식은 [reference/review-criteria.md](reference/review-criteria.md) 10절) + - 설계서·ADR → [research-design.md](research-design.md) + - 코드 동작이 바뀌어 문서를 따라 고치는 일 → 그 코드 변경의 playbook(같은 변경에서 고친다) + +## 2. 받아야 할 것 + +- 독자: 누가, 무엇을 하려고 읽나. 사람인가, 이력 없는 세션인가, 파생 서비스 개발자인가. +- 그 문서가 가리킬 정본: 규칙이 이미 어디에 있나. +- 위치와 분량 상한. +- 시험 방법: cold-read 시험을 누가 하나(보통 맡긴 쪽이 따로 한다). + +## 3. 크기와 사고 순서 + +- 오타·깨진 링크·한 문장 정정은 작음이다: 목적 한 줄, 대상 확인, 검증. +- 새 안내 문서나 playbook 하나는 중간이다. +- 문서 체계(매뉴얼 구성, 진입 경로)를 바꾸는 일은 큼이다. 소유자 검토가 먼저다. +- 선행 사례: 같은 독자를 둔 이 repo의 문서(`docs/manual/`, `docs/work/`)와, 그 문서를 읽고 일한 기록(보고, cold-read 시험 기록). +- 스킬: `technical-writing-best-practices`, `documentation-and-adrs`. 사람이 터미널에서 따라 하는 절차서면 `writing-practitioner-guides`. + +## 4. 절차 + +1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다". +2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `CLAUDE.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. +3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다. +4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. +5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다. +6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. +7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다. +8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다. +9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn '<파일 이름>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). +10. `docs/work/`나 루트 `CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0, playbook 뼈대, 상대 링크를 본다. +11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. +12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`. +13. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다. + +**playbook을 새로 만들 때의 뼈대** (모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다): + +`1. 언제 쓰나` · `2. 받아야 할 것` · `3. 크기와 사고 순서` · `4. 절차` · `5. 완료 기준` · `6. 하지 말 것` · `7. 막혔을 때` · `8. 보고 형식` · `9. 자주 하는 실수`(10줄 이하) + +## 5. 완료 기준 + +- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다. +- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다. +- 정본을 복사한 문장이 없다. 가리키는 줄만 있다. +- `docs/work/`·루트 `CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다. +- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그). +- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다. + +## 6. 하지 말 것 + +- 정본의 규칙을 문서에 다시 쓰지 않는다. 갈라진 복사본이 된다. +- 계획서를 나중에 고치지 않는다. 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 된다(`docs/README.md`). +- 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 처리 결과는 리뷰 README에 쓴다. +- 소유자 환경 규칙(실행 위치, 세션 도구)을 여러 곳에 쓰지 않는다. [operate.md](operate.md) 「실행 위치」와 [delegate.md](delegate.md) 「소유자 환경」에만 둔다. +- 분량 상한을 넘기지 않는다. 넘으면 같은 문서에서 한 줄을 빼거나 `reference/`로 내린다. + +## 7. 막혔을 때 + +- 정본끼리 다른 말을 하면 어느 쪽이 맞는지 정하지 않는다. 두 위치와 차이를 적어 묻는다. +- 소유자 파일(전역 `~/.claude/CLAUDE.md`, 사용자 설정·스킬, design-docs)을 고쳐야 하면 승인을 받고 고친다. + +## 8. 보고 형식 + +[README](README.md) 6절에 더해 적는다. + +- 바꾼 문서와 줄 수, 분량 상한 대비. +- 검사 결과: `check-work-docs.py`, `check-review-index.py`, 링크 검사, document-contract lane의 rc와 로그 경로. +- cold-read 시험이나 자가 점검: 써 본 brief, 막힌 곳, 고친 것. +- 정본과 다른 곳을 찾았으면 그 위치. + +## 9. 자주 하는 실수 + +- 지난 리뷰 ID로 이유를 대신한다. 내용과 날짜를 쓴다. +- 저장소 밖 문서를 상대 링크로 써서 링크 검사가 실패한다. 코드 표기로 쓴다. +- 없는 태스크 이름이나 옛 경로를 쓴다. 쓰기 전에 빌드 파일과 `ls`로 확인한다. diff --git a/docs/work/evidence.md b/docs/work/evidence.md new file mode 100644 index 00000000..2c2fe750 --- /dev/null +++ b/docs/work/evidence.md @@ -0,0 +1,150 @@ +# 근거와 이력 + +`docs/work/` 본문은 지난 리뷰를 모르는 사람도 읽을 수 있게 썼다. 그래서 규칙이 나온 사건과 지난 리뷰 ID는 본문에 넣지 않고 여기에 모았다. 본문을 따르는 데 이 문서는 필요 없다. 규칙의 이유를 확인하거나 규칙을 바꾸려 할 때 읽는다. + +표기: `1101/05-01`은 `docs/reviews/2026-11-01-maturity-review/`의 발견 05-01이다. `1103/RR6-01-05`는 `docs/reviews/2026-11-03-rereview/`의 발견이다(`RR-`는 1차 재리뷰, `RR2-`~`RR6-`는 round2~round6). `1101` README, `1103` README는 각 폴더의 `README.md`다. 「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번이다. + +## 1. 이 매뉴얼이 나온 곳 + +- 조사와 설계: design-docs `delegation-loop/01-research.md`(1~5단계), `delegation-loop/02-design.md`(6단계, 4·5·6·7·10절). 2026-11-06 소유자가 결정 D1~D14를 모두 권하는 안대로 승인했다. +- 공통 정본: design-docs `conventions/work-thinking-order.md`(작업 사고 순서), `conventions/delegation-loop.md`(위임 루프 운영). +- 재료: 옛 개선 매뉴얼 브랜치 `claude/improvement-manual-6ae516`(커밋 `3b66358e`, `319cff91`, `06477350`, 2026-11-05). 병합하지 않고 설계 10절 표대로 옮겼다(결정 D12). +- 옛 매뉴얼을 버린 이유(2026-11-06 소유자 판정): 조사 없이 만들었다, 범위가 리뷰·수정뿐이다, 본문 159줄에 지난 리뷰 ID가 있다, 진입 분량이 717줄이다, 시험한 적이 없다. + +옛 매뉴얼에서 옮긴 곳: + +| 옛 위치 | 새 위치 | +| --- | --- | +| README 「정본 표」, 적용 범위 | `docs/work/README.md` 1·7절, 각 playbook | +| 결정 M-5(저장소 밖 문서는 코드 표기), M-6(소유자 환경 규칙은 한 절에만) | `docs-writing.md` 4절, `operate.md` 4.1절 | +| 결정 M-3(심각도 두 체계) | `reference/review-criteria.md` 3절 | +| 결정 M-4(결정 표는 색인) | `reference/decisions.md` 머리말 | +| 결정 M-7(커밋 정책은 두고 예외만) | `docs/work/README.md` 4절, `AGENTS.md` 커밋 문장 | +| 결정 M-8(개선 제안도 닫는다) | `reference/review-criteria.md` 1절 | +| 결정 M-9(분업과 "Minor도 고친다"의 저장소 안 정본) | `improve.md` 4.5절, `delegate.md` | +| 결정 M-1(위치 `docs/improvement/`), M-2(프론트와 장 번호 맞추기) | 버림. 위치는 `docs/work/`, 두 repo는 장 번호 대신 같은 playbook 파일 이름을 쓴다 | +| 01장 판정표, 0절 공통 단계, 1~6절 | `docs/work/README.md` 3절, `improve.md` | +| 02장 | `reference/review-criteria.md`(지난 예는 이 문서 5절) | +| 03장 | `reference/review-criteria.md` 9절 | +| 04장 P1~P11 | `reference/defect-patterns.md` 「막는 기준」 | +| 05장 | `reference/review-criteria.md` 7절, `improve.md` 4.2·4.3절 | +| 06장 | `reference/review-criteria.md` 8절, `reference/gates.md` 5절, 기준선은 이 문서 6절 | +| 07장 | `reference/gates.md`, `operate.md` | +| 08장 | `reference/decisions.md` | +| 09장 | `delegate.md`, `improve.md` 4.4·4.5절, design-docs `conventions/delegation-loop.md` | +| 부록 결함 패턴 | `reference/defect-patterns.md` + 이 문서 4절 | + +## 2. 규칙과 사건 + +| 규칙(본문 위치) | 사건 | 근거 | +| --- | --- | --- | +| 무거운 실행은 desktop에서, 공유 잠금으로 (`operate.md` 4.1) | 2026-11-05 하위 세션 넷이 노트북에서 Gradle을 돌려 노트북 부하가 22까지 올랐다 | `1103` README 17.1절, design-docs `delegation-loop/01-research.md` 4.2절 | +| 진입 분량 상한, 본문 이력 ID 금지 (`docs/work/README.md` 8절) | 옛 개선 매뉴얼은 진입 717줄, 이력 ID가 든 본문 159줄 | `01-research.md` 4.1절 | +| 색인은 기계로 대조한다 (`improve.md` 4.1) | 원래 리뷰 색인이 119건이었다. 06 영역 문서의 `NN-10`~`NN-14` 5건이 색인과 모든 수정 묶음에서 빠졌다. 실제는 124건 | `1101` README 12절 정정, `1103` README 1절, `1103/RR-05-10` | +| 「새로 가정하는 것」 칸, 수정 묶음 크기 상한 (`improve.md` 4.4, 8절) | round6 발견 25건 중 17건(68%)을 직전 수정 커밋이 만들었다. 짝 프론트 1106 리뷰도 25건 중 16건(64%) | `01-research.md` 4.3절, design-docs `delegation-loop/02-design.md` 4.3절 | +| 보고한 태스크가 로그에 있는지 확인 (`improve.md` 9절, `gates.md` 4절) | 묶음 보고가 없는 태스크 `:adapter:outbound:persistence-jpa:documentContractTest`를 적었다 | `1103` README 17.2절 | +| 성능 lane은 workflow와 같은 단언 속성으로 (`gates.md` 5절) | r10 desktop 게이트의 `performanceCheck`가 `-Pperformance.assertions.enabled=true` 없이 돌아, httpclient 시간 단언 없이 통과했다 | desktop `~/r10-logs/gates.sh`, 공유 노트 「백엔드 개선 매뉴얼 인계」 | +| 묶음을 너무 크게 만들지 않는다 (`delegate.md` 4.2) | 알림·파일 서버를 한 묶음(r2-05a)으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다. 다음 라운드(r3-a)에 다시 올려 합쳤다 | `1101` README 14.3절, 16절 | +| 두 묶음이 같은 파일을 건드리지 않게 (`delegate.md` 4.2) | 2라운드 묶음 r2-06이 10개 파일 충돌로 처음부터 다시 작업했다 | `1101` README 14.1절 | +| 전 leaf import를 바꾸는 묶음은 마지막에 혼자 (`improve.md` 6절, `delegate.md` 4.2) | r3-G | `1101` README 15.1절 | +| 묶음마다 그 시점 최신 기준에서 시작 (`delegate.md` 4.2) | 3라운드가 2라운드보다 충돌이 적었다 | `1101` README 16.1절 | +| 합친 트리는 따로 검증 (`improve.md` 4.4, `gates.md` 3절) | 두 묶음의 수정이 한 트리에서 처음 만나 `BC_IMPOSSIBLE_INSTANCEOF`가 생겼다. 최종 게이트에서 드러난 2건 | `1101` README 16.1절, `1103` README 6.1절 | +| 캐시로 통과한 것은 그렇게 적는다 (`gates.md` 4절) | `ci`가 434초에서 51초로 준 것은 캐시 재사용이었다 | `1101` README 16.2절 | +| 같은 결함은 한 묶음에만 (`delegate.md` 4.2) | 같은 runbook 문장을 두 리뷰가 적어 한 번 고쳤다(`1103/RR6-01-07`, `1103/RR6-02-03`) | `1103` README 17절 | +| RED가 머신에 따라 통과하지 않게 (`improve.md` 7절) | watchdog RED 테스트가 공용 풀 병렬도 1인 머신에서 옛 코드도 통과시켰다 | `1103/RR4-03-01`, `1103` README 16절 r9-b | +| 실 vendor 결함은 실 vendor에서 RED (`improve.md` 4.2) | 새 실 PostgreSQL 테스트 3개의 수정 전 실패를 실 PostgreSQL로 확인하지 않았다 | `1101` README 14절 r2-04 | +| Agent 도구를 쓰지 않는다 (`delegate.md` 4.3) | 하위 세션 시작이 막히자 Agent 하위 에이전트로 우회했다. 지난 라운드는 사용량 한도 때문에도 하위 에이전트 없이 진행했다 | `01-research.md` 4.2절, `1101` README 16절, `1103` README 6절 | +| 예전 멈춤 기준을 거둠 (`improve.md` 4.5) | 2026-11-05 소유자 지시 "보고할 때 남은 문제가 없어야 한다". "새 Important 0이면 멈춤"(9.1절), "Minor는 기록만"(11.1절)을 거뒀다 | `1103` README 16절 | +| 종료 조건은 repo마다 (`improve.md` 4.5) | 2026-11-05 소유자 원문 "각자 유지" | 2026-11-05 총괄 세션 전달 | + +## 3. 수정 묶음 크기 (`improve.md` 4.4) + +추가 줄은 `git show --shortstat`의 insertions다(테스트·문서 포함). + +| 수정 커밋 | 고친 것 | 추가 줄 | 다음 확인 리뷰 | 그 리뷰의 발견 | +| --- | --- | --- | --- | --- | +| `01a8a2a70..5786126c`(커밋 3개) | 원래 리뷰 발견 | +60,167 | 1차 재리뷰 | Important 27, Minor 41 | +| `bbe944bd` | 1차 재리뷰 발견 + 색인에서 빠졌던 5건 | +13,479 | round2 | Important 7, Minor 22 | +| `1885bf8d` | 2차 재리뷰 결함 29건 | +5,495 | round3 | Important 0, Minor 19 | +| `f40c03c6` | Minor 19건(영역 묶음 4개) | +1,877 | round4 | Important 0, Minor 7 | +| `70fb80bf` | 소유자가 다시 정한 기본값 3가지 | +906 | round5 | Important 0, Minor 9 | +| `45d2a478` | 기록만 했던 결함 전부(영역 묶음 4개) | +5,420 | round6 | Important 2, Minor 23(17건은 이 커밋이 만듦) | +| `6e992970` | round6 결함 25건(영역 묶음 4개) | +5,143 | 아직 없음 | — | + +읽는 법: 추가 2,000줄 아래 두 번은 다음 발견이 7·9건, 5,000줄 위 네 번은 19·25·29·68건이었다. 상한(묶음 8건, 확인 리뷰당 1,500줄)은 이 표에서 정한 판단 값이다. 위임 루프 지표(라운드당 새 결함, 수정이 만든 결함 비율)로 다시 맞춘다. + +## 4. 결함 패턴의 근거 (`reference/defect-patterns.md`) + +| 패턴 | 근거 | +| --- | --- | +| A1 갈라진 복사본 | `1101/01-03`, `1101/01-07`, `1101/04-06`, `1101/05-09`, `1101/07-06`, `1101/01-11`, `1103/RR-01-14`, `1101` README 16.3절(템플릿 패키지 목록 두 곳), `1103` README 16절 r9-c(버전 정규식 사본) | +| A2 문서와 코드 불일치 | `1101/02-01`, `1101/07-11`, `1101/03-04`, `1101/06-11`, `1103/RR-01-03`, `1103/RR-01-11`, `1103/RR5-01-01`, `1103/RR6-02-05`, `1103/RR6-03-05`, `1103/RR6-04-05` | +| A3 선언과 실행이 떨어져 있다 | `1101/05-15`, `1101/03-11`, `1101/02-03`, `1101/07-06`, `1103/RR-06-01`, `1103/RR2-04-03`, `1103` README 6.1절(`redis.capability.*` 6개) | +| A4 결과 불명을 확실함으로 | `1101/05-01`, `1101/04-01`, `1101/06-01`, `1101/05-17`, `1101/05-11`, `1103/RR-02-03`, `1103/RR-01-11`, `1101` README 4절 원인 1 | +| A5 중복·경쟁을 코드 순서로 | `1101/09-02`, `1101/04-08`, `1101/04-02`, `1101/03-10`, `1101/04-13`, `1103/RR-03-01`, `1103/RR-02-04` | +| A6 주장하는 것을 보지 않는 테스트 | `1101/05-08`, `1101/02-02`, `1101/01-05`, `1103` README 14절(`CountDownLatch` 7건), `1103/RR4-03-01`, `1103/RR6-01-08`, `1103/RR6-02-02` | +| A7 거짓 통과 게이트 | `1101/08-01`, `1101/04-04`, `1101/03-12`, `1103/RR-06-02`, `1103/RR-06-03`, `1103/RR-04-05`, `1103` README 14절(테스트 SpotBugs 53개), `1103/RR3-04-02`, `1103/RR6-04-01`, r10 desktop `performanceCheck`(2절) | +| A8 로그로 새는 입력값·원인 | `1103/RR6-01-05`, `1103/RR6-01-06`, `1103` README 16절 r9-a, `1101/02-11`, `1101/01-04` | +| A9 이름만 보는 허용·거부 | `1103/RR-07-02`, `1103/RR2-04-02`, `1103/RR2-04-01`, `1101/07-14` | +| A10 글로만 있는 규칙 | `1103/RR-01-02`, `1101/04-03`, `1101/05-16` | +| A11 샘플·fixture가 운영과 다르게 조립 | `1101/07-03`, `1101/09-03`, `1101/09-08`, `1101/07-04`, `1101/01-02`, `1101/07-09` | +| A12 수정이 새 결함을 만든다 | `1103` README 1절(Important 27), 9절, `1103/RR6-01-01`(회귀), `1101` README 16.1절, `1103` README 6.1절, round6 68%(2절) | +| A13 합치는 과정의 누락 | `1101` README 12절 정정, `1101` README 14.1절(충돌 처리 목록) | +| A14 타이밍에 기댄 약속 | `1103` README 16.1절(`ClientRuntimeRegistry.close`), `1103/RR3-03-01`, `1101/05-06` | +| A15 사라지는 외부 공급원 | `1101/05-09`, `1101/08-04` | +| A16 상한 없는 자원 | `1101/03-06`, `1101/03-09`, `1101/04-10`, `1101/02-09`, `1101/04-12` | + +## 5. 리뷰 기준의 예 (`reference/review-criteria.md`) + +**결함의 모양(1절)**: 이름과 다른 동작 `1101/05-03`(`ONLY_IF_SOURCE_REVISION_NEWER`가 조건 없이 덮어씀), HARD-STOP 위반 `1101/07-08`(기본 조립 루트가 선택 capability를 앎), 갈라진 복사본 `1101/01-03`(`TenantId` 3벌)·`1101/04-06`(SQLState 표 2벌), 막지 못하는 게이트 `1101/05-08`(소유자 검사를 지워도 442개 통과)·`1101/08-01`(어떤 workflow도 돌리지 않는 strict lane 14개), 틀린 조치를 시키는 문서 `1103/RR-05-01`(DEAD 재발행 SQL을 따르면 다시 DEAD), 기본값 뒤에 숨은 위험 `1101/02-03`(JWT audience가 비면 검증을 건너뜀). + +**성격(2절)**: 구조적 위험 `1101` README 6절, 미검증 `1103` README 10.3절(CI runner가 꺼져 있다). + +**심각도(3절)**: 전체 리뷰 체계는 `1101` README 12절. High 예 `1101/05-01`, `1101/04-02`, `1101/02-03`. Medium 예 `1101/04-06`, `1101/04-05`. Low 예 `1101/07-11`. 확인 리뷰 체계는 `1103` README 2절 이후 모든 round, Important 기준은 `1103` README 11절, Minor 예는 `1103/round4/review.md`·`round6/`. "이번 커밋 / 이전부터"는 `1103/round6/04-build-logic.md` 「결론」. Minor도 고친다는 규칙은 `1103` README 16절, High·Important 재확인은 `1101` README 2절. + +**증거 수준(4절)**: 이전 결과를 쓰지 않은 예 `1101/09-performance-measurement.md` 1절, 섞인 증거 수준 표기 예 `1103/round6/03-persistence.md` RR6-03-01. + +**통제 수준(5절)**: M0 예 2026-11-01 시점 JPA 양방향 연관관계 금지(`1101/04-03`), M1 예 `@SystemInvoked`를 bean으로 등록하지 말라는 주석(`1103/RR-01-02`), M4 예 DB 유일 제약(`1101/09-02` 수정 뒤). + +**28개 관점(6절)의 지난 예**: 1 `1101/05-03` · 2 `1101/07-08`, `1101/08-05` · 3 `1101/01-07` · 4 `1101/01-01`, `1101/07-09` · 5 `1101/02-03`, `1103/RR-07-02` · 6 `1101/04-01`, `1101/06-01`, `1101/05-01` · 7 `1103/RR-05-01`, `1103` README 6.1절 · 8 `1103` README 16절 r9-a, `1101/01-04` · 9 `1101/04-06`, `1101/07-11` · 10 `1101/05-08`, `1101/02-02` · 11 `1101/09-02`, `1103/RR-02-09` · 12 `1101/04-02`, `1101/03-10` · 13 `1101/03-06`, `1101/03-09` · 14 `1101/09-01`, `1101/09-02` · 15 `1101/02-03`, `1101/07-03`, `1103/RR6-01-05` · 16 `1101/05-09`, `1101/09-09` · 17 `1101/02-01`, `1101/02-02` · 18 `1101/07-04`, `1101/06-02` · 19 `1101/05-15`, `1101/07-06` · 20 `1103/RR-01-01`, `1103/RR-01-03` · 21 `1101/08-01`, `1103/RR-06-02`, `1103` README 14절 · 22 `1101/04-13` · 23 `1101/01-03`, `1101/01-12` · 24 `1101/05-21` · 25 `1101/01-10` · 26 `1101/04-16` · 27 `1101/07-08`, `1101/05-19` · 28 `1101/03-10`, `1101/06-03`. + +**시나리오(6절)의 지난 추적**: `1101/01-core-and-feature-pattern.md` 4.1·4.2·4.4절, `1101/09-performance-measurement.md` 5.1~5.3절, `1101/05-05`·`05-06`·`05-01`, `1101/04-01`·`04-05`, `1103/RR-03-03`, `1101/06-01`, `1103/RR-03-02`, `1103/RR-02-09`·`RR-02-10`, `1101/04-02`·`03-10`, `1101/05-08`, `1101/03-01`·`02-09`, `1101/06-02`·`07-07`, `1101/08-build-ci-test.md` 4절. + +**테스트 점검표(7절)**: `1103/RR6-01-08`, `1101/02-02`, `1101/05-08`, `1103` README 14절, `1103/RR6-02-02`, `1103/RR6-01-03`, `1103` README 17절 r10-01, `1103` README 16.1절. fake 예 `1103/RR-01-04`, `1103` README 17절 r10-02(손 사본 20건 삭제, skip 17 → 0). + +**리뷰 문서 양식(10절)**: 전체 리뷰 README는 `1101` README 절 순서, 영역 문서는 `1101/01-core-and-feature-pattern.md`, 확인 리뷰 문서는 `1103/round6/*.md`, 확인 리뷰 발견 필드는 `1103/round6/03-persistence.md` RR6-03-01, 전체 리뷰 발견 필드는 `1101/08-build-ci-test.md` 08-01. + +## 6. 성능 기준선 (`improve.md` 4.3) + +잰 커밋과 함께만 쓴다. 현재 HEAD에서 다시 잰 값이 아니다. 성능 작업을 시작하면 현재 커밋에서 다시 재고 이 표와 비교한다. + +| 측정 | 값 | 커밋·출처 | +| --- | --- | --- | +| 기본 조합 bootJar / 기동 중앙값 / 빈 수 | 41.4 MB / 3.44 s / 407 | `01a8a2a70`, `1101/09-performance-measurement.md` 3.1절 | +| 샘플 bootJar / 기동 중앙값 / 빈 수 | 99.0 MB / 8.05 s / 603 | 같음 | +| 필터 체인만 지나는 요청 | 27,130 rps, p50 0.51 ms | 같은 문서 3.4절 (d) | +| 샘플 단건 조회 | 5,521 rps, p50 2.70 ms, SQL 7개 | 같은 문서 3.2·3.3절 | +| 샘플 목록 20건 | 829 rps, p50 15.54 ms, SQL 46개 | 같음(수정 전) | +| 샘플 목록 20건(수정 뒤) | SQL 46 → 6, 765 → 2,528 rps | `1101` README 14절 r2-09(묶음 보고 — E0, 다시 재지 않음) | +| 관측 기능 비용 | 처리량 약 3% | 같은 문서 3.4절 (b) | +| 가상 스레드 | 처리량 차이 없음(병목은 커넥션 10개와 DB 왕복) | 같은 문서 3.3절 | +| 설정만 바꾼 실험 | `hibernate.default_batch_fetch_size=100`만으로 목록 처리량 2.9배 | 같은 문서 3.4절 | +| 게이트 시간(desktop, 12코어·31GB) | `ci`+`verifyDependencyLocks` 5분 42초, `mainCheck` 8분 8초, `integrationCheck` 17분 10초 | `2c692554`, `1103` README 17.2절 | + +측정 스크립트(`run-app.sh`, `Load.java`, `sqlcount.sh`)는 그때 scratchpad에 두었고 repo에는 없다. 다시 재려면 `1101/09-performance-measurement.md` 「측정 명령 (다시 돌리는 법)」으로 다시 만든다. + +## 7. 리뷰 색인 대조 결과 (2026-11-06) + +`scripts/check-review-index.py`를 지난 리뷰 폴더 두 곳에 돌린 결과다(기준 커밋 `3d73b6f1`). + +| 폴더 | 명령 | 영역 문서 발견 | 색인에 있음 | 없음 | rc | +| --- | --- | --- | --- | --- | --- | +| `docs/reviews/2026-11-01-maturity-review/` | `--index-heading "12. 발견 색인"` | 124 | 124 | 0 | 0 | +| `docs/reviews/2026-11-03-rereview/` | README 전체 | 157 | 135 | 22 | 1 | + +- 2026-11-01 폴더: 지금은 모두 있다. 같은 검사를 사고 시점 커밋 `34565130`의 폴더에 돌리면 `NN-10`~`NN-14` 5건을 "자리표시자 영역"으로 잡고 rc=1로 실패한다. 이 검사가 그 사고를 막았을 것이다. +- 2026-11-03 폴더의 22건은 처리되지 않은 발견이 아니라 README가 ID로 적지 않은 발견이다. + - `RR-05-10`(색인 누락 5건 자체에 대한 발견)은 README 1절 정정과 6.1절이 내용으로 다룬다. + - `RR-07-05`(CSRF 제외 규칙의 이유)는 README 6절 r4-f 행이 내용으로 다룬다. + - 나머지 20건은 round6 Minor다(`RR6-01-02`~`06`·`08`·`09`, `RR6-02-02`·`04`·`05`, `RR6-03-02`~`05`, `RR6-04-01`~`06`). README 17절은 영역별 건수만 적었고, r10 묶음이 영역 단위로 고쳤다. +- 이 검사는 "색인에 이름이 있나"만 본다. 고쳤는지는 처리 표와 확인 리뷰가 본다. 앞으로의 리뷰 README는 모든 ID를 이름으로 적는다(`improve.md` 4.1절 7단계). diff --git a/docs/work/improve.md b/docs/work/improve.md new file mode 100644 index 00000000..954ea146 --- /dev/null +++ b/docs/work/improve.md @@ -0,0 +1,132 @@ +# 개선 — 리뷰, 결함 수정, 리팩터링, 성능, 구조, 테스트 구조 + +이미 있는 코드를 평가하거나 고치는 일의 절차다. 핵심은 하나다: 리뷰 → 수정 → 확인 리뷰를 발견이 0이 될 때까지 돈다. + +## 1. 언제 쓰나 + +| 지금 상태 | 작업 | +| --- | --- | +| 무엇이 틀렸는지 아직 모른다 | 리뷰 | +| 계약(이름·Javadoc·문서·레지스트리·테스트 이름이 약속한 것)과 다른 동작이 확인됐다 | 결함 수정 | +| 동작은 맞는데 구조 비용이 크다 | 리팩터링 | +| 숫자로 잰 비용이 크다 | 성능 최적화 | +| leaf·패키지·허용 의존이 바뀐다 | 구조 변경 | +| 테스트가 이름이 말한 것을 증명하지 못한다 | 테스트 구조 개선 | + +- 새 업무 기능은 [new-feature.md](new-feature.md)다. +- 고치기 전에 소유자 결정이 필요하면 [research-design.md](research-design.md)가 먼저다. + +## 2. 받아야 할 것 + +- 리뷰: 범위(전체 / 영역 / 커밋 범위 `..`와 pathspec), 쓸 심각도 체계(전체 리뷰용인지 확인 리뷰용인지). +- 수정: 고칠 발견 목록(ID, 위치)과 리뷰 문서 경로. +- 공통: 기준 커밋, 브랜치, 커밋 허용 여부, 검증할 게이트. +- 그 발견에 필요한 소유자 결정이 났는지. [reference/decisions.md](reference/decisions.md)에 없고 brief에도 없으면 그 발견만 멈추고 묻는다. + +## 3. 크기와 사고 순서 + +- 보통 중간이다: 확인 리뷰 하나, 수정 묶음 하나. +- 큼: 전체 리뷰, 구조 변경, 공개 계약을 바꾸는 수정. 큰 일은 1~5단계 결과와 대안을 소유자가 먼저 본다. +- 이 작업에서 선행 사례는 둘이다: 같은 원인이 남은 다른 자리, 그리고 [reference/defect-patterns.md](reference/defect-patterns.md)의 같은 모양. +- 대안은 고치는 법 2~3개를 비교한다. 고른 것과 버린 것을 커밋 본문에 쓴다. +- 스킬: 리뷰는 `superpowers:requesting-code-review`의 리뷰어 지침과 바뀐 경계의 영역 스킬, 결함 수정은 `superpowers:systematic-debugging` → `superpowers:test-driven-development`, 리팩터링은 `refactor`·`codebase-design`, 성능은 `performance-optimization`, 구조 변경은 `superpowers:brainstorming` → `superpowers:writing-plans`. 리뷰 결과를 받아 고칠 때는 `superpowers:receiving-code-review`. +- 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 이 세션이 직접 한다. 나눠야 하면 [delegate.md](delegate.md)대로 별도 세션에 맡긴다. + +## 4. 절차 + +### 4.1 리뷰 + +1. 범위를 고정한다. 확인 리뷰는 pathspec과 `git diff --stat .. -- ` 결과를 문서에 적는다. +2. 확인 리뷰는 수정 보고의 「새로 가정하는 것」 칸부터 본다. 가정마다 다른 코드·설정·운영에서 참인지 확인한다. +3. 그다음 수정 diff와, diff가 바꾼 동작의 주변 코드를 읽는다. 확인 리뷰는 저장소 전체가 아니라 그 수정만 본다. +4. 전체 리뷰는 게이트를 먼저 한 번 돌려 결과를 적고([reference/gates.md](reference/gates.md)), 영역을 나눈다([delegate.md](delegate.md) 「나누는 법」). +5. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 옮겨 쓸 수 있게 남기고(소유자 환경에서는 공유 노트 폴더, design-docs `conventions/delegation-loop.md` 11절), worktree는 지운다. +6. 발견을 [reference/review-criteria.md](reference/review-criteria.md) 양식으로 적는다. 발견마다 증거 수준과 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. +7. 리뷰 폴더 README에 색인을 만든다. 발견 ID를 모두 이름으로 적는다. 범위(`A~B`)와 이어 쓰기(`A·07`)는 된다. 건수만 쓰지 않는다. +8. `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 색인 절이 따로 있으면 `--index-heading "<절 제목>"`을 붙인다. rc=0이어야 한다. +9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다. + +### 4.2 결함 수정 + +1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다. +2. RED: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지가 그 결함을 말해야 한다. 컴파일 오류나 준비 실패는 RED가 아니다. +3. 수정과 테스트를 이미 같이 썼으면, 기준 커밋에 테스트만 얹은 임시 worktree에서 RED를 본다. 실 DB·Redis가 필요한 결함은 실 vendor lane에서 본다. +4. 가장 작은 수정으로 GREEN을 본다. +5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다. +6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`CLAUDE.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다. +7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 더하고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. +8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)). + +### 4.3 리팩터링, 성능, 구조, 테스트 구조 + +- 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다. +- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `CLAUDE.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다. +- 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.md 「성능 측정」, 지난 기준선은 [evidence.md](evidence.md)다. 지난 숫자는 현재 커밋에서 다시 잰다. +- 구조 변경: 설계서(`docs/superpowers/specs/`)와 계획서(`docs/superpowers/plans/`)를 먼저 둔다. review-criteria.md 「leaf 변경 체크리스트」를 따른다. ArchUnit 규칙을 바꾸면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다. +- 테스트 구조: 지금 테스트가 증명하는 것(이름, 단언, skip 수)을 적는다. 고친 뒤 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지(변이) 본다. 옮겼으면 lane별 테스트 수를 전후로 비교한다. + +### 4.4 수정 묶음의 크기 + +- 묶음 하나는 리뷰 영역 하나 안이고 발견 8건 이하다. 묶음마다 커밋 하나다. +- 확인 리뷰 하나가 보는 수정 diff는 추가 1,500줄 이하다(`git diff --shortstat ..`, 테스트 포함, lockfile·스냅숏 같은 생성 파일 제외). 넘으면 묶음 커밋별로 나눠 따로 확인 리뷰한다. +- 왜: 지난 수정 라운드에서 추가 줄이 2,000줄 아래면 다음 확인 리뷰 발견이 9건 이하였고, 5,000줄을 넘으면 19건 이상이었다([evidence.md](evidence.md) 「수정 묶음 크기」). 상한 값은 판단이다. 라운드당 새 결함 수로 다시 맞춘다. +- 묶음을 합친 트리는 따로 검증한다([reference/gates.md](reference/gates.md) 「라운드 끝」). 두 묶음의 수정은 한 트리에서 처음 만날 때 새 결함을 만든다. + +### 4.5 멈춤 기준 — 이 repo는 하나다 + +리뷰 → 수정 → 확인 리뷰는 아래 넷이 모두 참일 때만 멈춘다. + +1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다. Minor도 기록만 하지 않고 고친다. +2. 열린 「Declined to judge」가 0이다. +3. 합친 트리에서 라운드 끝 게이트가 모두 통과했다. +4. 리뷰 README의 남은 항목이 0이다. 결정으로 닫은 항목은 결정 위치를 적었다. + +- 다른 멈춤 기준은 이 repo에서 쓰지 않는다. "새 Important가 0이면 멈춤"과 "Minor는 기록만"은 소유자가 거뒀다. 짝 프론트 repo는 자기 기준을 쓴다(소유자 결정 "각자 유지"). +- 코드로 닫을 수 없는 것은 소유자 결정이 필요한 항목뿐이다. 근거와 권하는 안을 붙여 질문으로 보고하고, 답을 받으면 다시 고친다. + +## 5. 완료 기준 + +- 리뷰: 모든 발견이 양식대로이고 증거 수준이 있다. 색인 검사가 rc=0이다. 결정이 필요한 항목마다 선택지와 권하는 안이 있다. +- 결함 수정: 수정 전 실패(RED)와 수정 뒤 통과(GREEN) 로그가 있다. 같은 원인의 다른 자리를 확인했다. 해당 게이트가 rc=0이다(desktop 로그 경로). 보고에 「새로 가정하는 것」이 있다. +- 리팩터링: 보존 조건 테스트가 전후 모두 통과하고 `architectureCheck`가 통과한다. 지운 코드를 가리키는 문서·주석이 grep으로 0이다. +- 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과). +- 구조 변경: `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`가 통과한다. 문서에 leaf 개수를 적지 않았다. +- 테스트 구조: 변이가 잡혔다. 새 lane이 단계에 속한다. `testQualityCheck`가 통과한다. +- `docs/work/`나 루트 `CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다. + +## 6. 하지 말 것 + +- 리뷰 중에 코드를 고치지 않는다. 리뷰는 읽기 전용이다. +- 이전 라운드의 실행 결과나 묶음 보고의 "통과"를 현재 증거로 쓰지 않는다. 바뀐 커밋에서 다시 돌린다. +- 정한 결정을 결함으로 다시 올리지 않는다. 전제가 틀렸다는 새 증거가 있을 때만 근거와 함께 다시 연다. +- 범위 밖 결함을 고치지 않는다. 버리지도 않는다. 위치와 함께 「Declined to judge」나 보고의 「범위 밖에서 본 것」에 적는다. +- 같은 결함을 여러 번 세지 않는다. 두 영역이 같은 결함을 적으면 색인에서 하나로 합친다. +- 어딘가에 적용된 마이그레이션 파일을 고치지 않는다. +- 전 leaf의 import를 바꾸는 이동을 다른 묶음과 동시에 하지 않는다. 나머지를 합친 뒤 혼자 마지막에 한다. + +## 7. 막혔을 때 + +- 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다. +- RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다. + +## 8. 보고 형식 + +[README](README.md) 6절에 더해, 고친 발견마다 아래 칸을 쓴다. 리뷰 README의 처리 표에 그대로 옮길 수 있게 쓴다. + +| 칸 | 적을 것 | +| --- | --- | +| 발견 | 고친 발견의 ID와 한 줄 내용(brief와 리뷰 문서에서는 ID를 쓴다) | +| 상태 | 완료 / 부분(무엇이 남았나) / 못 함(이유) | +| RED | 수정 전 실패한 테스트 이름과 수, 로그 경로 | +| 검증 | 명령, 테스트 수, rc, 로그 경로 | +| 처리 내용 | 바꾼 것, 고치다 새로 찾아 고친 것 | +| 새로 가정하는 것 | 이 변경이 다른 코드·설정·운영에 새로 기대는 것. 확인 리뷰가 여기서 시작한다 | +| 정한 기본값 | 소유자가 확인할 것 | +| 범위 밖에서 본 것 | 위치와 내용. 고치지 않았다 | + +## 9. 자주 하는 실수 + +- 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다. +- 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다. +- 성능 lane을 workflow와 다른 속성으로 돌린다. [reference/gates.md](reference/gates.md) 「성능 lane」을 따른다. +- 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다. diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md new file mode 100644 index 00000000..73007fff --- /dev/null +++ b/docs/work/new-feature.md @@ -0,0 +1,79 @@ +# 새 기능 — 업무 기능과 capability 모듈 만들기 + +이 playbook은 입구다. 만드는 순서와 판단 지점은 개발 매뉴얼 [`docs/manual/`](../manual/README.md)이 정본이다. 여기에는 크기, 완료 기준, 하지 말 것만 더한다. + +## 1. 언제 쓰나 + +- 새 업무 기능(도메인 개념, 유스케이스, endpoint)을 더할 때. +- 새 capability 모듈(의존성 한 줄로 켜지는 부가 기능)을 만들 때. +- 아니면 다른 playbook이다. + - 있는 기능의 결함·구조를 고친다 → [improve.md](improve.md) + - 어디에 둘지, 어떤 저장소를 쓸지 같은 결정이 먼저 필요하다 → [research-design.md](research-design.md) + - 있는 capability를 켜거나 끈다(`runtimeOnly` 한 줄) → 이 playbook의 4절 3단계에서 `docs/manual/10-capabilities.md`만 따른다 + +## 2. 받아야 할 것 + +- 기능 이름(PascalCase, 예: `Invoice`)과 경로 이름이 규칙대로 안 될 때의 경로(`--path`). +- 요구사항: 무엇을 저장하나, 누가 호출하나, 어떤 권한인가, 재전송될 수 있는 쓰기인가. +- 저장소 선택(어떤 persistence leaf, 마이그레이션 번호대). 서비스마다 달라 사람이 정한다(`docs/manual/04-persistence.md`). brief에 없으면 묻는다. +- 공개 계약(HTTP 경로, 오류 코드, env 키)을 새로 만드는지. 만들면 크기는 큼이다. +- 기준 커밋, 브랜치, 커밋 허용 여부. + +## 3. 크기와 사고 순서 + +- 업무 기능 하나는 보통 중간이다: 계층 leaf 여러 곳에 파일이 생기지만 판단은 매뉴얼이 정해 둔 범위 안이다. +- 큼: 새 capability 모듈, 새 leaf, 새 공개 계약, 파생 서비스가 따라 고쳐야 하는 변경. 큰 일은 설계와 소유자 검토가 먼저다([research-design.md](research-design.md)). +- 선행 사례는 생성 명령의 출력 하나다. `src/sample-portfolio`는 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일 제약)의 참고일 뿐 배치를 따라 하지 않는다. +- 스킬: 설계가 바뀌면 `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 안 `` 패키지다. 이름이 템플릿 패키지(`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 변경 체크리스트」를 따른다. +4. 뼈대를 만든다: `scripts/new-feature.sh `(`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). +7. 동작은 테스트를 먼저 쓴다. 포트마다 fake 하나와 공유 계약(`XxxRepositoryContract`)을 포트 소유 leaf의 `testFixtures`에 두고, 실제 adapter도 같은 계약을 실 DB lane에서 상속한다. +8. 건드린 leaf마다 `check`, 경계를 넘었으면 `architectureCheck`, 바뀐 표면의 검사를 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). +9. `docs/manual/11-checklist.md`를 한 줄씩 확인한다. +10. 매뉴얼과 코드가 다른 곳을 찾았으면 매뉴얼을 고치는 변경을 따로 낸다(정본이 맞다). + +## 5. 완료 기준 + +- `docs/manual/11-checklist.md`의 항목이 모두 참이다. 아닌 항목은 이유를 보고에 적었다. +- 건드린 leaf의 `check`와 `architectureCheck`가 desktop에서 rc=0이다. 로그 경로가 보고에 있다. +- 공개 경로·env 키·의존성을 바꿨으면 `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`·`verifyDependencyLocks`가 rc=0이다. +- 저장 adapter가 있으면 공유 계약을 실 DB lane에서 상속하고, 그 lane이 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run`). +- capability 모듈이면 완료 기준 7개가 모두 참이고, 모듈 README에 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)가 있다. +- 생성 명령의 템플릿이나 패키지 규칙을 바꿨으면 `verifyFeatureScaffold`가 통과한다. + +## 6. 하지 말 것 + +- `AGENTS.md` HARD-STOP을 어기지 않는다. 특히 controller가 repository를 부르거나, inbound DTO가 application으로 들어가거나, 업무 규칙이 mapper·filter·설정에 들어가는 것. +- `src/sample-portfolio`의 배치(한 leaf에 모든 계층)를 따라 하지 않는다. onboarding 테스트 fixture도 따라 하지 않는다. +- 업무 코드를 템플릿 패키지에 넣지 않는다. +- 저장 adapter를 `persistence-jpa` leaf 안에 만들지 않는다. 서비스 전용 persistence leaf에 둔다. +- 한 단계가 다른 leaf나 계층을 고쳐야 하면 범위를 조용히 넓히지 않는다. 거기서 멈추고 설계를 다시 본다(7절). +- bootstrap에 capability 이름·스위치 목록·scan 정규식을 넣지 않는다. 모듈이 자기 `AutoConfiguration.imports`로 켜진다. +- 노트북에서 Gradle을 돌리지 않는다. + +## 7. 막혔을 때 + +- 저장소 선택, 공개 계약, 권한 매핑처럼 매뉴얼이 "사람이 정한다"고 한 것은 근거와 권하는 안을 붙여 한 번 묻고 그 부분만 멈춘다([README](README.md) 5절). +- 매뉴얼의 판단 지점이 이 기능에 맞지 않으면(기본값도 예외도 해당 없음) 멈추고 묻는다. 새 판단 지점은 매뉴얼에 더할 후보로 보고한다. + +## 8. 보고 형식 + +[README](README.md) 6절에 더해 적는다. + +- 만든 기능과 배치: leaf별 패키지와 주요 타입. +- 읽은 매뉴얼 장과 그 장에서 고른 기본값·예외. +- 정한 것(소유자 확인 대상): 경로, 권한 이름, 오류 코드, 마이그레이션 번호. +- 11장 체크리스트 결과: 참이 아닌 항목과 이유. + +## 9. 자주 하는 실수 + +- 샘플을 베껴 한 leaf에 모든 계층을 둔다. 생성 명령의 출력을 따른다. +- 생성 명령을 노트북에서 기본 옵션으로 돌려 Gradle이 노트북에서 돈다. `--no-format`을 쓴다. +- 역할 → 권한 매핑을 빠뜨려 쓰기 API가 모든 요청에 403이다. `docs/manual/07-authorization.md`를 본다. diff --git a/docs/work/operate.md b/docs/work/operate.md new file mode 100644 index 00000000..3128b753 --- /dev/null +++ b/docs/work/operate.md @@ -0,0 +1,115 @@ +# 운영 — 게이트 실행, desktop 검증, 릴리스, 파생 서비스 + +검증을 실제로 돌리고, 릴리스하고, 템플릿 변경을 파생 서비스에 넘기는 절차다. 무엇을 돌릴지는 [reference/gates.md](reference/gates.md)가 정하고, 이 playbook은 어디서 어떻게 돌리는지 정한다. + +## 1. 언제 쓰나 + +- 다른 playbook의 검증 단계에서 Gradle·Docker·테스트·게이트를 돌릴 때(4.1·4.2절). +- 여러 묶음을 합친 트리를 라운드 끝 게이트로 검증할 때. +- 릴리스 태그 전 확인을 할 때(4.3절). +- 템플릿 변경을 파생 서비스가 받을 수 있게 준비할 때(4.4절). +- 게이트 자체(build-logic, workflow)를 고치는 일은 [improve.md](improve.md)다. + +## 2. 받아야 할 것 + +- 대상 브랜치와 커밋 sha. desktop은 push된 브랜치만 받을 수 있다. +- 자기 브랜치 push 허용 여부. desktop 검증이 필요한 일이면 brief가 허용해야 한다. main push는 허용되지 않는다. +- 돌릴 게이트 목록(없으면 [reference/gates.md](reference/gates.md) 2절로 정한다)과 로그를 둘 이름. + +## 3. 크기와 사고 순서 + +- 게이트를 돌리고 기록하는 일은 보통 작음이다: 목적 한 줄, 대상 확인, 실행과 기록. +- 라운드 끝 전체 묶음, 첫 실행이 실패해 원인을 찾는 일은 중간이다. 실패 원인 찾기는 `superpowers:systematic-debugging`. +- 릴리스와 파생 서비스 쪽 병합은 소유자가 정한다. + +## 4. 절차 + +### 4.1 실행 위치 — 소유자 환경 + +> 이 절은 이 repo 소유자의 기계에 묶인 규칙이다. 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다. 다른 환경(파생 서비스 등)은 이 절만 자기 환경으로 바꾼다. + +- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** +- 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`에 있다. + +절차: + +```bash +# 1) 노트북: 검증할 변경을 자기 브랜치에 커밋하고 push한다(brief가 허용한 경우) +git push origin <자기 브랜치> + +# 2) desktop: 기존 checkout을 건드리지 않게 따로 worktree를 만든다 +ssh desktop +cd ~/workspace/clean-architecture-backend-template +git fetch origin +git worktree add ~/workspace/<작업 이름> origin/<자기 브랜치> +mkdir -p ~/<작업 이름>-logs +uptime # 다른 빌드가 돌고 있는지 부하를 본다 + +# 3) 공유 잠금 아래에서 한 번에 하나씩 돌리고 rc와 로그를 남긴다 +cd ~/workspace/<작업 이름>/src +flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?" + +# 4) 끝나면 worktree를 지운다 +cd ~/workspace/clean-architecture-backend-template +git worktree remove ~/workspace/<작업 이름> +``` + +- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. +- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다. +- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다. + +### 4.2 게이트 실행과 기록 + +1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절 묶음 전체다. +2. 잠금을 얻은 뒤 1분 부하를 적고 돌린다. 한 번에 하나씩이다. +3. 첫 실행이 실패하면 원인을 찾아 고치고 다시 돌린다. 첫 실행과 다시 돌린 결과를 둘 다 적는다. +4. 결과를 [reference/gates.md](reference/gates.md) 4절 형식으로 적는다: 게이트, rc, 시간, 직전 부하, 로그 경로, 대상 커밋. +5. 보고한 태스크 이름과 테스트 수가 로그에 있는지 grep으로 확인한다. + +### 4.3 릴리스 + +- 릴리스는 `v*` 태그 push로 시작한다(`.github/workflows/release.yml`). 태그와 push는 소유자가 한다. +- 태그 전에 그 커밋에서 `./gradlew :releaseCheck -PgitRevision= --console=plain`을 desktop에서 돌린다. sha 없이 돌리면 설계대로 실패한다. +- 태그는 PR 게이트와 main 단계를 이미 통과한 main 커밋에서 자른다. 그래서 `releaseCheck`는 `ci`를 다시 돌리지 않는다. +- 이미지 서명·SBOM은 workflow가 한다(cosign keyless). + +### 4.4 파생 서비스에 템플릿 변경 넘기기 + +- 파생 서비스는 이 템플릿을 받아 도메인을 채운 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에서 고친다. +- 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다. + +## 5. 완료 기준 + +- brief가 요구한 게이트마다 rc, 시간, 직전 부하, desktop 로그 경로, 대상 커밋이 있다. +- 못 돌린 게이트는 이유가 있다. 캐시로 통과한 것과 집계가 뺀 lane을 적었다. +- desktop에 만든 worktree를 지웠다(`git worktree list`에 없다). 기존 checkout의 브랜치와 `stash@{0}`가 그대로다. +- 노트북에서 Gradle·Docker를 돌리지 않았다. + +## 6. 하지 말 것 + +- 노트북에서 Gradle·Docker·테스트를 돌리지 않는다. +- 잠금 없이 desktop에서 무거운 명령을 돌리지 않는다. +- desktop 기존 checkout에서 브랜치를 바꾸거나 stash를 꺼내지 않는다. 자기 worktree를 쓴다. +- 다른 브랜치나 main에 push하지 않는다. 태그를 만들지 않는다. +- 첫 실행 실패를 지우고 두 번째 성공만 보고하지 않는다. + +## 7. 막혔을 때 + +- desktop에 접속할 수 없거나 잠금이 오래 풀리지 않으면 기다린 시간과 상태(`uptime`, 잠금을 쥔 프로세스)를 적어 묻는다. 노트북에서 대신 돌리지 않는다. +- 게이트가 이 일과 무관해 보이는 이유로 실패하면 같은 게이트를 기준 커밋에서 돌려 원래 있던 실패인지 가린다. 원래 있던 실패면 보고하고 그 게이트만 멈춘다. + +## 8. 보고 형식 + +[README](README.md) 6절에 더해 [reference/gates.md](reference/gates.md) 4절 표를 붙인다. desktop 정리 결과(지운 worktree, checkout 브랜치, `stash@{0}` 상태)를 한 줄로 적는다. + +## 9. 자주 하는 실수 + +- desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다. +- 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다. +- performance lane을 workflow와 다른 속성으로 돌린다. [reference/gates.md](reference/gates.md) 5절을 따른다. diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md new file mode 100644 index 00000000..f0506d09 --- /dev/null +++ b/docs/work/reference/decisions.md @@ -0,0 +1,188 @@ +# 결정 색인 + +이미 정한 것을 한곳에서 찾는 색인이다. 결정의 원문은 「출처」 칸의 문서에 있고, 원문이 정본이다. 이 표와 원문이 다르면 원문이 맞고 이 표를 고친다. 이 문서는 지난 리뷰 ID와 결정 번호를 출처로 쓴다(매뉴얼 본문에는 쓰지 않는다). + +```text +작업 시작 ─> 이 색인에서 주제를 찾는다 ─> 있으면: 원문을 읽고 그대로 따른다 + └> 없으면: 소유자 몫인가? ─> 그렇다: 묻는다(3절) + └> 아니다: 정하고 기록한다(3절) +``` + +## 1. 결정을 다시 묻지 않는 규칙 + +1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 **내용**을 옮겨 적는다. +2. 다시 열 수 있는 경우는 셋뿐이다. + - 결정의 전제가 코드나 측정으로 틀렸다고 확인됐다. + - 두 결정이 서로 충돌한다. + - 결정이 `AGENTS.md` HARD-STOP과 충돌한다. +3. 다시 열 때는 "다시 따져 본 것"과 권하는 안을 붙여 소유자에게 묻는다. 예: 2026-11-04 소유자가 수정 묶음의 기본값 셋을 다시 물었을 때, 총괄은 각각 근거를 다시 따져 적었고 소유자가 다시 정했다(`docs/reviews/2026-11-03-rereview/README.md` 15절). +4. 위임·기본값으로 정한 것은 보고에 따로 적는다. 소유자가 뒤집을 수 있게 한다. +5. 뒤집힌 결정은 원문에서 지우지 않는다. 취소선이나 "→ N절에서 바꿈"으로 새 위치를 가리킨다. +6. 리뷰어는 정한 결정을 결함으로 다시 올리지 않는다. + +## 2. 색인 + +「누가」 칸: **소유자**는 소유자가 직접 정했다. **위임**은 소유자가 "지금 정하고 진행하라"고 맡겨 총괄이 정했다(소유자가 뒤집을 수 있다). **기본값**은 수정 묶음이 정하고 처리 표에 남겼다(소유자 확인 대상). **총괄 지시**는 소유자 환경을 운영하려고 총괄 세션이 정한 작업 규칙이다. **정책**은 `AGENTS.md`에 적힌 규칙이다. + +「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번, `1101`은 `docs/reviews/2026-11-01-maturity-review/README.md`, `1103`은 `docs/reviews/2026-11-03-rereview/README.md`다. + +### 2.1 작업 방식 + +| 주제 | 결정 | 누가 | 날짜 | 출처 | +| --- | --- | --- | --- | --- | +| 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 | +| 커밋 예외 | brief가 허용하면 그 작업의 자기 브랜치에만 커밋·push한다. main 병합·다른 브랜치 push·force push는 하지 않는다 | 소유자 | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절, `docs/work/README.md` 4절 | +| 커밋 예외(지난 것) | `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절 | +| 옛 멈춤 기준 | "새 Important 0이면 멈춤", "Minor는 기록만" — 거둠 | 위임 → 소유자가 거둠 | 2026-11-05 | `1103` 9.1·11.1·16절 | +| 두 repo의 종료 조건 | 각자 유지한다. 백엔드는 발견이 0이 될 때까지, 짝 프론트는 자기 매뉴얼의 조건 | 소유자 | 2026-11-05 | 2026-11-05 총괄 세션 전달(소유자 원문 "각자 유지") | +| 무거운 실행 위치 | 노트북에서 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 | +| 크기별 생략 | 작음·중간·큼으로 사고 순서 단계를 줄인다. 크기는 맡기는 쪽이 정하고 맡은 쪽은 올리기만 한다 | 소유자 | 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 | +| 학습 문서 | 삭제된 코드를 설명하는 학습 문서(`docs/study/*.ko.md`, `docs/*-superpowers-package/`)는 현재 코드에 맞게 갱신 | 소유자 | 2026-09-25 | 결정 6 | +| client 오류 문구 | 한국어. `Category`별 문구 표 하나를 shared-contract에 | 소유자 | 2026-09-25 | 결정 11 | + +### 2.2 구조·조립 + +| 주제 | 결정 | 누가 | 출처 | +| --- | --- | --- | --- | +| 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) | +| 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 | +| notification `TenantId` | 통합하지 않음. 차이와 이유는 그 타입 Javadoc | 위임 | `1101` 15절(01-03) | +| 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` 15절(r2-10) | +| `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) | +| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b | + +### 2.3 계약·오류 + +| 주제 | 결정 | 누가 | 출처 | +| --- | --- | --- | --- | +| HTTP 오류 응답 | Envelope 하나. fileserver problem+json도 Envelope로, tus 프로토콜 헤더만 유지 | 소유자 | 결정 2 | +| 처리 중 409 | `IDEMPOTENT_IN_FLIGHT`는 `retryable=true` + `Retry-After: 2`, 계약 문서에 고정 | 소유자 | `1101` 5절(02-01), 15절 | +| Envelope null 필드 | 백엔드가 생략(`NON_NULL`) | 소유자 | `1101` 5절(02-02) | +| `INTERNAL_ERROR` retryable | `false`. 일시적 실패는 전용 코드가 retryable을 가진다 | 소유자 | 결정 28 | +| 새 오류 코드 소유 | 코드를 쓰는 leaf의 enum. 계약은 `docs/web/http-contract.md` §4 | 위임 | `1101` 15절 | +| correlation ID | 규칙 밖이면 서버가 새 값으로 교체 | 위임 | `1101` 15절(02-11) | +| JSON 아닌 본문 상한 | 전역 상한 없음. 엔드포인트가 직접 둔다 | 위임 | `1101` 15절(02-09) | +| GraphQL 복잡도 | 크기 미선언 list = 20, `first`·`last` 둘 다면 큰 쪽, per-parent 경고 임계 10 | 위임 | `1101` 15절(03-01·03-03) | +| GraphQL DataLoader 키 실패 | 등록된 `ApiErrorCode`만 노출 | 소유자 | 결정 25 | +| Draft-12 offset 불일치 | problem 문서는 프로토콜 예외로 유지 | 소유자 | 결정 12 | +| 알림 category 생략 | 거부(400), 판정은 유스케이스 | 소유자 | 결정 13 | + +### 2.4 멱등성 + +| 주제 | 결정 | 누가 | 출처 | +| --- | --- | --- | --- | +| complete 단계 연결 포화 | `UNAVAILABLE` 현재 동작 유지 + 문서화 | 소유자 | 결정 24 | +| complete 단계 저장소 실패 | "결과 불명"으로 따로 알린다(실행 전 503과 구분). 같은 키 재전송은 서버가 판정 | 위임 | `1103` 4절(RR-02-03) | +| lease 지난 실행 중 기록 | PostgreSQL·Redis store가 같은 계약: 작업을 다시 돌리지 않고 "회복 필요" | 위임 | `1103` 9.1절(RR-01-11) | +| Redis key TTL | claim·renew 모두 key TTL ≥ max(replay TTL, processing lease), 설정 검사 | 위임 | `1103` 9.1절(RR-03-11) | +| 늦은 완료 | 늦게 끝난 첫 시도의 완료는 **기록한다**(묶음 기본값 "버린다"를 뒤집음). 다시 실행은 여전히 하지 않음 | 소유자 | `1103` 15절 ① | +| 보존 기간 관계 | `failure-retention < replay-ttl`이면 기동 실패 | 소유자 | `1103` 15절 ③ | +| 같은 attempt 재claim | lease 지난 `CLAIMED`·`FAILED_RETRYABLE`을 넘겨받는다. 같은 attempt를 두 호출이 동시에 쓰는 것은 호출자 계약 | 기본값 | `1103` 17절 r10-02 | +| 다른 핸들의 시작 답 | PostgreSQL도 Redis와 같게 `NOT_OWNER`/`NOT_CLAIMED`로 답한다 | 기본값 | `1103` 17절 r10-02 | +| Redis 연결 예산 | 캐시 조건부 쓰기는 멱등성·lease와 다른 연결 예산(SCRIPT lane) | 위임 | `1103` 4절(RR-04-02) | + +### 2.5 영속성 + +| 주제 | 결정 | 누가 | 출처 | +| --- | --- | --- | --- | +| JPA 기본값 | 트랜잭션 제한 30초, JDBC batch 50, H2 운영 jar 제거, 격리 수준 Hikari 고정, upsert `DO NOTHING` 후 갱신 | 위임 | `1101` 15절(04) | +| 포트 시그니처 | claim에 lease·`claimFence`, fileserver `claimDue`·`markAbandoned`·`claimToken` | 위임 | `1101` 15절 | +| 마이그레이션 번호 | 스트림별 순번. 샘플은 운영 스트림과 합쳐 도는 테스트가 있어 `V8_1`. notification은 `V13` | 위임 | `1101` 15절 | +| V21 유일 인덱스 | 기존 중복이 있으면 마이그레이션 실패. runbook에 확인 쿼리 | 위임 | `1101` 15절 | +| 순서 번호 seed | counter가 없으면 전역 floor부터 | 위임 | `1103` 4절(RR-03-02) | +| 마이그레이션 잠금 | 강한 잠금을 거는 마이그레이션은 `SET LOCAL lock_timeout`, 같은 모양의 lane 테스트 | 위임 | `1103` 9.1절(RR-02-09) | +| Flyway PostgreSQL 잠금 | 세션 수준(`transactional-lock: false`). 전제: Hikari 직접 연결. transaction-mode PgBouncer 뒤에서는 깨진다 | 기본값 | `1103` 17절 r10-03(RR6-03-01) | +| persistence-jpa 설정 prefix | 플랫폼 자체는 `app.persistence-jpa.*`, 공유 기능은 기능 트리(`app.outbox`·`app.lock`·`app.realtime.replay`) | 소유자 | 결정 36 | +| 분산 lock·lease | 둘 다 capability로 유지, 공통 계약 테스트 | 소유자 | 결정 8 | + +### 2.6 샘플·메시징·보안·설정 + +| 주제 | 결정 | 누가 | 출처 | +| --- | --- | --- | --- | +| 포스터 업로드 abort·reconcile 경합 | 먼저 끝난 쪽이 이김(이미 게시됐으면 abort는 409) | 소유자 | 결정 22 | +| work log 권한·batch | 관리자도 남의 work log 수정 불가, `batchCreate` 상한 1000·한 트랜잭션 | 위임 | `1101` 15절(09) | +| 이벤트 tenant·오류 코드 | 이벤트 tenant 범위 `global`, `WORKLOG_INVALID`·`OPERATION_NOT_FOUND` | 위임 | `1101` 15절(01) | +| outbox append 모델 | canonical(`OutboxAppendPort`)로 통일, legacy 포트·legacy Kafka 발행 경로 삭제 | 소유자 | 결정 7 | +| Kafka 소비 | 지원. `MessageHandler` 하나 + starter-kafka가 consumer 조립 | 소유자 | 결정 10 | +| decode 타입 등록 | handler bean이 선언한 타입으로 decode 목록을 만든다 | 위임 | `1101` 15절(06-08 후속) | +| relay 재시도 | 재시도 가능 거부는 무한 재시도(5분 간격), 예산 설정 키 없음, 인증 오류는 경보로 | 위임 | `1101` 15절(06-01·06-03) | +| 끝나지 않는 재시도 | bridge가 원인 코드를 행에 남기고, 오래 재시도 중인 행 수·나이를 지표로, runbook에 park·재개 절차와 테스트된 SQL | 위임 | `1103` 4절(RR-05-03) | +| 카드 검증기 YAML | messaging leaf 테스트에서만 snakeyaml(main 금지) | 소유자 | 결정 29 | +| JWT audience·role | audience 필수, 자기 client role만(기존 배포는 env 하나를 채움) | 소유자 | `1101` 5절(02-03), 15절 | +| 데모 계정 | `local`·`test`·`demo` 프로필이 명시적으로 켜졌을 때만(허용 목록). 각 프로필은 sample이 실제로 뜨는 프로필 | 위임 | `1103` 4절(RR-07-02), 9.1절(RR2-04-02) | +| `fixture-` 값 거부 | 비밀로 분류된 키(`docs/registries/secrets-classification.yaml`)만 검사 | 위임 | `1103` 9.1절(RR2-04-01) | +| 파일 서버 인가 | 역할 검사(`file:*` 권한)와 소유자·tenant 검사(`ownerPrincipalId`)를 둘 다 | 소유자 | 결정 14, 결정 32 | +| cross-origin redirect | 호출자 헤더 전부 제거, 안전한 헤더만 유지 | 소유자 | 결정 23 | +| 개발 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 | +| 로그 설정 | logback이 `app.logging.*`을 읽음, `APP_CACHE_REDIS_TTL_JITTER` deprecated | 위임 | `1101` 15절(07) | +| 빈 env 값 | 선택 숫자 설정의 빈 값은 "미설정". 오타·모르는 키 거부는 그대로 | 위임 | `1101` 15절 | +| `APP_FLYWAY_ENABLED` | dev·prod에도 적용 | 위임 | `1101` 15절(r3-F) | +| 전송 상한 기본값 | gRPC 스레드 32·큐 256·동시 100·deadline 10s·drain 2s, ledger `claimTtl` 5m·보존 24h, WebSocket `max-connections` 1000(초과 시 1013) | 위임 | `1101` 15절(03-06·03-09·03-10) | + +### 2.7 빌드·게이트·capability + +| 주제 | 결정 | 누가 | 출처 | +| --- | --- | --- | --- | +| 빌드 게이트 | `verifyEnvKeys`는 app-bootstrap 태스크로 유지(구현은 build-logic `ca.config-contract`), JPA evidence manifest는 폐기하고 leaf 테스트로, redis topology lane 유지 | 소유자 | 결정 4 | +| API surface 단계 | PR(leaf `check` 안) | 소유자 | 결정 20 | +| PR `ci` 범위 | 변경 모듈만 돌리지 않음. 전체 실행 + Gradle 캐시(보류) | 소유자 | 결정 30 | +| 의존성 checksum | 추가 안 함(보류) | 소유자 | 결정 19 | +| build-logic 의존성 잠금 | 잠그지 않음 + 문서화(보류) | 소유자 | 결정 27 | +| 릴리스 이미지 서명 | cosign keyless, tag 릴리스에서 서명·검증 | 소유자 | 결정 31 | +| gRPC `.proto` | protobuf Gradle 플러그인 + Buf(CI) | 소유자 | 결정 18 | +| SpotBugs 신뢰도 | MEDIUM으로 내림. 패턴 단위 제외는 이유를 단다 | 위임 | `1101` 15절(08-07) | +| 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 | +| lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) | +| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② | +| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `AGENTS.md` 「Gradle 정책 권위」 | +| MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) | +| Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | `1101` 15절(09-11) | +| httpclient reactive | 삭제 | 소유자 | 결정 9 | +| SES 연동 | AWS SDK(sesv2) | 소유자 | 결정 17 | +| durable operation | HTTP 어댑터 추가, 설계 4개(서버 생성 id, payload 지문으로 재제출 판정, 고정 event type, 1일 보존) 승인 | 소유자 | 결정 15, 결정 26 | +| 알림 provider profile 소실 | 일반 재시도 정책 후 FAILED | 소유자 | 결정 21 | +| notification INGEST_ONLY | runtime 없이도 accept 때 route 이름 기록 | 위임 | `1101` 15절(r3-I) | +| 파일 서버 쿼터 | 상한 미설정 = 무제한, 동시 예약은 상한을 넘을 수 있음, 정리 worker 기본 켜짐 | 위임 | `1101` 15절(r2-05a) | +| objectstorage | provider type 하나 추가 | 위임 | `1101` 15절(05-16) | +| 에이전트가 원칙에서 바로 정한 것 | Kafka 주소 키 하나, composition이 persistence-jpa를 함께 가져옴 등 7건 | 기본값 | `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」 끝 목록 | +| 묶음별 기본값 | 각 라운드 처리 표의 「결정」 칸(예: SES replay 창 1h, Retry-After 30) | 기본값 | `1101` 13·14·16절, `1103` 6·10·12·15·16·17절 표 | + +## 3. 새 결정을 기록하는 법 + +**누가 정하나** + +| 소유자에게 묻는다 | 직접 정하고 기록한다 | +| --- | --- | +| 공개 계약·wire 형식 변경, 파생 서비스 동작을 바꾸는 기본값, 보안 정책, 새 leaf, 커밋 정책, 되돌리기 비싼 선택, 비용이 드는 외부 일 | 기존 원칙에서 바로 따라 나오는 것, 결함 수정의 구현 방법, 문서 위치 | + +**묻는 법**: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람을 한 표로 쓴다. + +**어디에 쓰나** + +| 결정의 종류 | 위치 | +| --- | --- | +| 리뷰 라운드에서 나온 결정 | 그 라운드 README의 「결정」 절. 항목 · 결정 · 이유 · 버린 대안 | +| 수정 묶음의 구현 기본값 | 처리 표의 「결정」 칸 | +| 되돌리기 비싼 아키텍처 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md`(기존 번호를 잇는다) | +| 매뉴얼을 만들거나 고치며 정한 것 | 이 색인 + 근거는 `docs/work/evidence.md` | +| 여러 repo와 소유자 운영에 걸친 결정 | design-docs | + +**기록한 뒤**: 이 색인에 한 줄(주제 · 결정 · 누가 · 날짜 · 출처)을 더한다. diff --git a/docs/work/reference/defect-patterns.md b/docs/work/reference/defect-patterns.md new file mode 100644 index 00000000..590ff58c --- /dev/null +++ b/docs/work/reference/defect-patterns.md @@ -0,0 +1,131 @@ +# 결함 패턴 + +이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다. + +계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 모듈 책임, 금지된 지름길)와 가장 가까운 `src/**/CLAUDE.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다. + +## 패턴 + +### A1. 갈라진 복사본 + +- **모양**: 같은 규칙·표·정규식·상수·이미지 참조가 여러 곳에 있고 이미 다르다. +- **막는 기준**: 규칙·표·정규식·상수·이미지 참조는 한 곳에 둔다. 두 곳이 꼭 필요하면 하나를 정본으로 명시하고, 다른 하나가 정본과 같은지 보는 대조 테스트를 둔다. +- **볼 것**: 새로 쓴 상수·정규식·표가 이미 어딘가에 있는지 grep. 같은 판정을 두 클래스가 하는지. +- **장치**: 정본을 가져다 쓰기(예: 마이그레이션 버전 판정 정본 `VersionedMigrationFiles`를 grpc 빌드가 Sync 태스크로 가져온다), 대조 테스트(`TemplatePackageOwnershipDocumentTest`). 테스트 lane의 컨테이너 이미지는 `src/config/testing/container-images.properties` 한 곳이다(MinIO qualification 이미지만 objectstorage leaf 소유). + +### A2. 문서와 코드 불일치 + +- **모양**: 계약·runbook·매뉴얼·README·Javadoc·실패 메시지가 현재 동작과 다르다. +- **막는 기준**: 동작을 바꾸는 변경은 그 동작을 설명하는 모든 문서를 같은 변경에서 고친다. 대상: `docs/web/http-contract.md`, `docs/registries/`, runbook, 매뉴얼, leaf README·`CLAUDE.md`, Javadoc, 업그레이드 안내. 고친 뒤 옛 표현을 grep으로 찾아 남은 곳을 없앤다. +- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/CLAUDE.md`를 grep. +- **장치**: 일부만 있다. runbook 숫자와 상수를 비교하는 document-contract lane, runbook SQL을 실 PostgreSQL에서 그대로 실행하는 lane. 나머지는 리뷰가 본다. 이 repo는 문서 전체를 파싱하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 8절). + +### A3. 선언과 실행이 떨어져 있다 + +- **모양**: 설정 키는 바인딩되지만 동작하지 않는다. 선언한 설정 bean이 조용히 바인딩되지 않는다. 레지스트리 행·지표를 아무 코드도 쓰지 않는다. +- **막는 기준**: 선언(설정 키, 레지스트리 행, 지표 이름, 옵션)마다 그것을 실행하는 코드가 있어야 한다. 실행 코드가 없으면 선언을 지운다. 동작하지 않는 옵션은 설정 키 자체를 두지 않는다(`AGENTS.md` capability 기준 3). +- **볼 것**: 새 설정 키를 읽는 곳, 새 레지스트리 행을 내보내는 곳, 문서가 말한 옵션의 분기. 기동 rule이 `static @Bean`이고 필드 주입이 없는지. +- **장치**: `StrictSettingsBinder`(모르는 키·오타 거부), `verifyEnvKeys`, 레지스트리와 코드를 대조하는 테스트(`ErrorCodeRegistryMappingTest`, `HeaderRegistryRuntimeAlignmentTest` 등). + +### A4. 결과 불명을 "확실함"으로 기록한다 + +- **모양**: 외부 효과의 결과를 모르는데 "시작 안 함", "재시도 가능", "확정 거부"로 기록한다. 또는 반대로 확실한 실패를 결과 불명으로 부풀린다. +- **막는 기준**: 외부 효과(DB 커밋, 알림 발송, broker 전송)의 결과를 모르면 "결과 불명"으로 기록·응답한다. 결과 불명을 자동으로 다시 실행하지 않는다. 확실히 실패한 것을 결과 불명으로 부풀리지 않는다. +- **볼 것**: 외부 호출 전후의 상태 기록 순서, 예외를 retryable·terminal·unknown으로 나누는 분기, 응답의 `retryable`. +- **장치**: 멱등성 공유 계약(`IdempotencyStoreContract` — PostgreSQL·Redis store가 같은 판정), `PersistenceExceptionTranslator`의 커밋 단계 분류, `docs/adr/ADR-JPA-003-completion-unknown.md`. + +### A5. 중복·경쟁을 코드 순서로 막는다 + +- **모양**: 조회 후 insert, 찾고 없으면 넣기, 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim, 프로세스 메모리에 둔 소유권. +- **막는 기준**: 유일성은 DB 유일 제약이 막고, adapter는 그 제약 위반만 기능 예외로 바꾼다. 여러 인스턴스가 집는 작업은 트랜잭션 안의 claim + lease로 소유권을 정한다. +- **볼 것**: 존재 확인 뒤 쓰기, 트랜잭션 밖 잠금, 메모리 안 소유권. +- **장치**: `CallerTransaction`(store는 호출자 트랜잭션을 요구), 동시 요청 통합 테스트(`CreatePosterConcurrencyIntegrationTest`). 정본: `docs/manual/04-persistence.md`. + +### A6. 주장하는 것을 보지 않는 테스트 + +- **모양**: 이름이 말한 성질을 단언하지 않는다. 지키려는 코드를 지워도 통과한다. 시간 제한 대기의 결과를 버린다. 계약 케이스를 skip한다. +- **막는 기준**: [review-criteria.md](review-criteria.md) 7절 점검표. 변이로 확인한다. skip은 0이거나 설계 이유를 적는다. +- **장치**: 포트당 fake와 공유 계약 상속(`AGENTS.md` 테스트 작성 규칙 6), `rejectSkipped`. + +### A7. 거짓 통과 게이트 + +- **모양**: 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈, 시간 단언을 끈 채 돈 performance lane. +- **막는 기준**: [gates.md](gates.md) 6절. 게이트 장치를 바꾸면 일부러 망가뜨린 입력으로 실패하는 것을 본다. +- **장치**: `verifyStrictLaneStages --dry-run`(두 빌드), lane 정책 값의 캐시 입력 선언, `testQualityCheck`. + +### A8. 로그로 새는 입력값·원인 + +- **모양**: 클라이언트 입력이나 SQL 원인이 로그 메시지에 실린다. 서버 실패를 남기지 않거나 클라이언트 실패를 ERROR로 남긴다. +- **막는 기준**: 클라이언트 탓 실패(입력 오류)는 WARN 한 줄로 남기고 입력값을 싣지 않는다. 서버 실패는 전송마다 같은 실패 로그 줄(`ServerFailureLog`)을 쓰고, 원인 체인의 SQL·입력값을 메시지에 붙이지 않는다. 클라이언트가 보낸 식별자가 규칙 밖이면 서버가 새 값으로 바꾼다. +- **볼 것**: 새 `log.warn`·`log.error`의 인자, 예외 메시지에 사용자 입력을 넣는 곳, 전송별 예외 처리기. +- **장치**: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java`(`refusedArgument` 포함), 비밀 분류 `docs/registries/secrets-classification.yaml`. + +### A9. 이름만 보는 허용·거부 + +- **모양**: 프로필·환경 이름 하나가 다르면 위험한 기능이 열린다. 허용한 값으로는 실제로 동작하지 않는다. +- **막는 기준**: 위험한 기능(데모 계정, 비밀 검사 면제 등)은 거부 목록이 아니라 허용 목록으로 연다. 허용 목록의 값마다 실제로 그 값으로 동작해야 한다. +- **볼 것**: 프로필·환경 이름 문자열 비교, 허용 값마다 실제로 기동하는 테스트가 있는지. +- **장치**: `SampleDemoProfilesStartupSystemTest`(허용 프로필마다 기동). + +### A10. 글로만 있는 규칙 + +- **모양**: "하지 마라", "반드시"가 주석·Javadoc·문서에만 있고 막는 장치가 없다(통제 M0~M1). +- **막는 기준**: 위반하면 데이터·권한이 깨지는 규칙은 기동 실패, ArchUnit, 타입으로 막는다. +- **볼 것**: "must not", "하지 않는다", "금지", "반드시"가 붙은 문장마다 막는 장치가 있는지. +- **장치**: 이유를 요구하는 표시(`@SystemCaller(reason)`), 기동 rule, ArchUnit. + +### A11. 샘플·fixture가 운영과 다르게 조립된다 + +- **모양**: 샘플이 자동 설정을 빼거나 런타임 기본값이 다르다. "따라 할 모양"으로 둔 fixture가 기동하지 않는다. +- **막는 기준**: 샘플은 운영과 같은 자동 설정과 런타임 기본값을 쓴다. 무엇을 빼면 이유와 대체 장치를 같은 곳에 적는다. 새 기능의 모양으로 둔 fixture는 실제로 기동되는 모양이어야 한다. +- **볼 것**: 샘플 `@SpringBootApplication(exclude=…)`, 샘플 `application.yml`과 기본 조합의 차이. +- **장치**: 샘플 전체 기동 lane(`:sample-portfolio:systemTest`, `mainCheck`), 샘플 실서버 계약(`sampleWebContractCheck`). + +### A12. 수정이 새 결함을 만든다 + +- **모양**: 고친 커밋에서 새 Important·회귀가 나온다. 두 수정이 한 트리에서 처음 만나 새 결함이 생긴다. +- **막는 기준**: 수정 보고에 「새로 가정하는 것」을 쓰고 확인 리뷰가 그 칸부터 본다. 수정 묶음 크기 상한을 지킨다([improve.md](../improve.md) 4.4절). 합친 트리를 라운드 끝 게이트로 따로 검증한다. +- **장치**: 확인 리뷰(수정 diff만), [gates.md](gates.md) 3절. + +### A13. 합치는 과정의 누락 + +- **모양**: 색인을 손으로 옮기다 발견이 빠진다. 손으로 푼 충돌이 한쪽 변경을 지운다. +- **막는 기준**: 색인은 영역 문서에서 기계로 대조한다. 두 묶음이 같은 파일을 건드리지 않게 나눈다([delegate.md](../delegate.md) 「나누는 법」). +- **장치**: `python3 scripts/check-review-index.py docs/reviews/<폴더>`. + +### A14. 타이밍에 기댄 약속 + +- **모양**: "스레드를 남기지 않는다", "시간 안에 끊는다"가 공용 풀이나 "보통은 끝나 있다"에 기댄다. +- **막는 기준**: 그런 약속은 join·종료 대기·전용 스레드로 보장한다. +- **볼 것**: `awaitTermination` 뒤 스레드 생존 확인, 시간 제한을 거는 실행기가 공용인지. +- **장치**: 부하·자원 한계 lane(`httpClientPerformanceTest` 등, `performanceCheck`). + +### A15. 사라지는 외부 공급원 + +- **모양**: 고정한 컨테이너 이미지를 더는 받을 수 없어 다른 lane 결과까지 가린다. +- **막는 기준**: 테스트 이미지는 한 곳에 digest로 고정하고, pull 실패는 따로 구분되는 메시지로 실패하게 한다. +- **장치**: `src/config/testing/container-images.properties`, `PinnedImageUnavailableException`, main 단계 `--continue`. + +### A16. 상한 없는 자원 + +- **모양**: 연결·구독·동시 호출·본문 크기·트랜잭션 시간·큐 길이에 상한이 없거나 코드에 드러나지 않는다. +- **막는 기준**: 상한이 있고 그 값이 코드나 설정에 드러난다. 상한을 넘으면 정해진 응답(예: WebSocket 1013, gRPC 즉시 닫기)을 준다. +- **정한 값**: [decisions.md](decisions.md) 「전송 상한 기본값」, JPA 기본 트랜잭션 제한 30초. JSON 아닌 본문 상한은 엔드포인트가 직접 둔다. + +## 코드에 결정을 드러내는 곳 + +고칠 때 "왜 이 모양인가"를 코드 가까이에 남긴다. 다음 리뷰가 같은 질문을 다시 하지 않게 하려는 것이다. + +| 경우 | 남기는 곳 | +| --- | --- | +| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc | +| 정적 분석 제외 | 제외 항목 옆 이유(`src/config/spotbugs/exclude-test.xml` 등) | +| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) | +| 복사본을 남긴 이유 | 가까운 `CLAUDE.md`(예: `src/messaging/CLAUDE.md`) | +| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` | + +## 패턴을 더하는 법 + +- 새 라운드에서 **두 건 이상**이 같은 모양이면 행을 더한다. 한 건이면 그 라운드 README에만 둔다. +- 모양은 원인 추측이 아니라 코드에서 실제로 본 모양을 쓴다. 근거 ID는 [evidence.md](../evidence.md)에 쓴다. +- 번호는 다시 매기지 않는다. 지운 패턴은 행을 남기고 "합침 → A"으로 적는다. diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md new file mode 100644 index 00000000..4ed57d7b --- /dev/null +++ b/docs/work/reference/gates.md @@ -0,0 +1,129 @@ +# 게이트 + +무엇을, 언제, 어디서 돌리는지 정한다. 게이트 구성의 정본은 `src/build.gradle`의 라이프사이클과 `.github/workflows/`다. 이 문서와 그 둘이 다르면 그 둘이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 [operate.md](../operate.md) 「실행 위치」다. + +```text +작업 중 :check (+ 그 leaf의 관련 strict lane) +묶음 끝 + architectureCheck · 바뀐 표면의 검사(env 키·공개 경로·의존성 잠금) · 관련 lane +라운드 끝 합친 트리에서 3절 묶음 전체 — workflow가 PR·main에서 돌리는 것과 같은 명령 +``` + +## 1. 게이트 목록 + +명령은 모두 `src/`에서 실행한다. leaf의 Gradle path는 `src/config/architecture/modules.json`의 `gradle_path`에서 읽는다. leaf별 명령 목록을 문서에 적지 않는다. + +| 게이트 | 무엇 | 단계 | 정의·workflow | +| --- | --- | --- | --- | +| `./gradlew :check` | 그 leaf만: 컴파일, 테스트, Spotless, Checkstyle, Error Prone, API surface | 작업 중 | leaf 컨벤션 플러그인 | +| `architectureCheck` | 의존 방향, domain-core·shared-contract·application-* 순수성, Git이 옮길 수 있는 소스, ArchUnit | PR(`ci` 안) | `src/build.gradle` | +| `./gradlew :app-bootstrap:architectureTest` | 저장소 전체 ArchUnit suite만 | 작업 중 | app-bootstrap `architectureTest` source set | +| `qualityCheck` | SpotBugs, FindSecBugs(운영 코드) | PR(`ci` 안) | `src/build.gradle` | +| `testQualityCheck` | 같은 분석을 모든 테스트 source set에(`config/spotbugs/exclude-test.xml` 기준) | main(`mainCheck` 안), optional 빌드는 `ci` | `src/build.gradle` | +| `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR | `ci-quality-gates.yml`: `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` | +| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | `ci-quality-gates.yml`, optional 빌드는 `-p optional-platforms` | +| `:sample-portfolio:check :sample-portfolio:qualityCheck` | 샘플(`ci` 밖) | PR | `ci-quality-gates.yml` | +| `-p optional-platforms ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml` | +| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` | +| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 샘플 실서버 계약 + 샘플 전체 기동(`:sample-portfolio:systemTest`) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` | +| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml`, optional 빌드도 | +| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). main·nightly에서 돈다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 | +| `releaseCheck -PgitRevision=` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` | +| `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리와 profile YAML·`.env.example` | `mainCheck` 안(`configContractCheck`) | build-logic `ca.config-contract` | +| `verifyPublicPathSnapshot` | 기본 공개 경로가 `docs/security/public-paths-snapshot.txt`와 같은가 | `mainCheck`·`releaseCheck` 안 | `src/build.gradle` | +| `verifyDependencyLocks` | lockfile | PR | `ci-quality-gates.yml` | +| `:app-bootstrap:documentContractTest` | 문서와 코드를 대조하는 lane(태그 `document-contract`) | main(`mainCheck` 안) | `src/app-bootstrap/build.gradle` | +| `:app-bootstrap:repositoryContractTest` | 빌드 스크립트·workflow·compose를 읽는 계약(태그 `repository-contract`) | PR | `src/app-bootstrap/build.gradle` | + +- leaf의 `check`는 그 leaf만 본다. 저장소 전체 질문은 이름이 따로 있는 루트 태스크가 답한다. +- 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다. +- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. + +## 2. 바꾼 것에 맞춰 고르기 + +| 바꾼 것 | 추가로 돌릴 것 | +| --- | --- | +| 한 leaf 안의 코드 | 그 leaf `check` + 그 코드를 지키는 strict lane(실 DB 등) | +| leaf 경계·의존·registry | `architectureCheck`, `verifyDependencyLocks` | +| env 키 | `:app-bootstrap:verifyEnvKeys` | +| 공개 경로·보안 체인 | `verifyPublicPathSnapshot` | +| 의존성 | `verifyDependencyLocks` | +| 문서(`docs/**`, `CLAUDE.md`, README) | 그 문서를 읽는 document-contract lane(예: `:app-bootstrap:documentContractTest`) + 링크 검사(아래) | +| `docs/work/`, 루트 `CLAUDE.md` | `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` 안) | +| 마이그레이션 | persistence-jpa `check`, 잠금 대기 lane(`postgresqlMigrationLockWaitIntegrationTest`), 마이그레이션 lane | +| 테스트 코드 | 그 leaf `testQualityCheck` | +| compose·Dockerfile | compose 검사 스크립트, 실제 `docker build`와 기동 | + +어떤 테스트가 그 문서를 읽는지는 `grep -rn '<파일 이름>' src --include=*.java`로 찾는다. + +**링크 검사**: 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가 없는 곳에서는 `python3 scripts/check-work-docs.py --links docs`로 상대 링크만 확인한다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). + +## 3. 라운드 끝 — 합친 트리의 전체 묶음 + +여러 묶음을 합친 트리는 workflow와 같은 명령으로 검증한다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다. + +```bash +cd src +./gradlew :ci :verifyDependencyLocks --warning-mode=fail --console=plain +./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --console=plain +./gradlew :verifyStrictLaneStages --dry-run --console=plain +./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --console=plain +./gradlew :mainCheck --continue --warning-mode=fail --console=plain +./gradlew :integrationCheck --continue --console=plain +./gradlew -p optional-platforms ci integrationCheck performanceCheck -Pperformance.assertions.enabled=true --console=plain +./gradlew :performanceCheck --continue -Pperformance.assertions.enabled=true --console=plain +./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --console=plain +cd .. && bash scripts/verify-compose-profile-contracts.sh +``` + +- 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다. +- 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다. + +## 4. 결과 기록 + +| 게이트 | 결과 | 시간 | 실행 직전 1분 부하 | 로그 | +| --- | --- | --- | --- | --- | +| `:ci :verifyDependencyLocks --warning-mode=fail` | rc=0 | 5분 42초 | 2.65 | desktop `~/<작업 이름>-logs/ci.log` | + +함께 적는다: + +- 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다. +- 못 돌린 것과 이유. 이유 없이 빠진 검증은 HARD-STOP 6 위반이다. +- 캐시로 통과한 것. 실행 시간이 짧으면 캐시 재사용인지 적는다. +- 집계가 뺀 lane. 입력이 없어 빠진 lane의 이름. +- 고친 테스트가 실제로 돌았는지. 큰 집계 안에서 몇 개가 돌았는지 테스트 수로. +- 보고한 태스크가 로그에 있는지. 로그에서 태스크 이름을 grep해 확인한다. + +## 5. 성능 lane + +- 일부 performance lane은 시간 단언을 `performance.assertions.enabled` 속성으로 켠다. workflow는 이 값을 `true`로 준다(`integration-main.yml`의 `GRADLE_OPTS`). +- leaf마다 기본값이 다르다: httpclient lane은 `false`(`src/adapter/outbound/httpclient/build.gradle`), persistence-mongo lane은 `true`(`src/adapter/outbound/persistence-mongo/build.gradle`). +- 그래서 desktop에서 `performanceCheck`를 돌릴 때는 workflow와 같게 `-Pperformance.assertions.enabled=true`를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다. +- 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 `performanceCheck`에 있다. + +회귀를 막는 장치: + +| 장치 | 고정하는 것 | 단계 | +| --- | --- | --- | +| 요청당 SQL 수 단언(`WorkLogStatementCostSystemTest`) | 목록 20건과 100건의 문장 수가 같음, 제목만 바꾸는 PATCH가 컬렉션 행을 건드리지 않음, batch 생성이 JDBC batch로 감 | sample `systemTest`(`mainCheck`) | +| 자원 한계 lane | Tomcat·Jetty 부하·느린 클라이언트·종료, HTTP client 풀·스트리밍·재시도, Hikari 풀 | `performanceCheck` | +| JMH 벤치마크 | `src/messaging/messaging-kafka/src/jmh`, `src/messaging/messaging-testkit/src/jmh`, `src/adapter/outbound/httpclient/src/jmh` | 명시 실행 | + +## 6. 게이트를 믿을 조건 — 거짓 통과 막기 + +초록이라는 사실만으로 그 게이트가 무언가를 막았다는 뜻은 아니다. + +| 거짓 통과 모양 | 지금의 장치 | +| --- | --- | +| 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) | +| optional 빌드를 보지 않음 | optional 빌드도 같은 검사 | +| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `AGENTS.md` 「Gradle 정책 권위」의 세는 규칙 | +| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 | +| 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) | +| 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 | +| 시간 단언을 끈 채 performance lane 실행 | 5절 속성 | +| 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` | + +게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다. diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md new file mode 100644 index 00000000..de30a617 --- /dev/null +++ b/docs/work/reference/review-criteria.md @@ -0,0 +1,283 @@ +# 리뷰 기준 + +리뷰와 수정에서 무엇을 결함으로 보고, 어떻게 판정하고, 어떤 형식으로 적는지 정한다. [improve.md](../improve.md)가 필요할 때 이 문서의 절을 가리킨다. 지난 리뷰에서 실제로 나온 예는 [evidence.md](../evidence.md) 「리뷰 기준의 예」에 있다. + +공용 리뷰 가이드는 이 repo 밖에 있다: design-docs `conventions/template-maturity-review-guide.md`. 아래 「가이드 N절」은 그 문서의 절이다. 이 문서는 가이드 없이도 판정할 수 있게 썼다. 일반 설명이 더 필요할 때만 가이드를 읽는다. + +## 1. 결함이란 + +리뷰는 **약속과 실제 동작이 다른 곳**을 찾는다. 약속은 코드 이름, Javadoc, 문서, 레지스트리, 테스트 이름, 게이트가 한 것이다. 약속을 어긴 증거가 있으면 결함이고, 없으면 개선 제안이다. + +| 결함의 모양 | 증거 | +| --- | --- | +| 이름·Javadoc·문서가 말한 동작과 실제 동작이 다르다 | 코드 경로 또는 실행 결과 | +| `AGENTS.md` HARD-STOP을 어긴다 | 의존 방향 게이트, ArchUnit, 코드 | +| 같은 규칙·값·표가 두 곳 이상에 있고, 서로 다르거나 같게 지키는 장치가 없다 | 두 위치와 차이 | +| 테스트나 게이트가 통과하지만 막겠다고 한 것을 막지 못한다 | 변이 실험, 실행 그래프 대조 | +| 운영자·개발자에게 틀린 조치를 시키는 문서 | 문서대로 실행한 결과 | +| 위험한 동작이 기본값·설정 뒤에 숨어 있다 | 기본값과 그 효과 | + +**개선 제안**은 계약 위반 없이 이해나 비용을 줄일 여지다. 현재 선택과 대안을 비교해 적는다(가이드 41절). 받으면 고치고, 받지 않으면 이유를 결정으로 남긴다. 기록만 하고 열어 두지 않는다. + +다음 말은 결함 근거가 아니다. + +| 근거가 아닌 말 | 결함으로 적으려면 | +| --- | --- | +| "추상화가 많다" | 어느 wrapper가 무엇을 보호하지 않는지, 지우면 무엇이 유지되는지 | +| "운영 준비가 안 됐다" | 어떤 절차를 어떤 버전에서 실행한 증거가 없는지 | +| "업계 표준이 아니다" | 이 repo의 어느 계약을 어기는지 | + +## 2. 발견의 성격 + +| 성격 | 뜻 | +| --- | --- | +| 확인된 결함 | 현재 커밋의 코드·실행으로 계약 위반을 보였다. 정적 증거만으로도 확정할 수 있다 | +| 구조적 위험 | 인과 경로는 있으나 영향 확인이 남았다. 예: 다중 인스턴스 경쟁을 코드 경로로만 봤다 | +| 미검증 | 이 환경에서 확인할 수 없다. 예: 실제 CI runner 실행 | +| 개선 제안 | 1절 | + +## 3. 심각도 + +심각도 체계는 둘이다. 리뷰 종류로 고른다. + +**전체 리뷰 — Critical / High / Medium / Low, 우선순위 P0~P3** (가이드 35.2·35.3절) + +| 등급 | 이 repo에서 | +| --- | --- | +| Critical | 인증 없이 민감정보 접근, 실제 데이터의 비가역 대량 손상 | +| High | 지원 조건에서 업무 중복 실행, 결과 불명 작업의 재실행, 기본 조합에서 보안 검사가 꺼짐 | +| Medium | 피해가 제한되거나 변경 비용을 반복해서 올림 | +| Low | 가독성·편의, 제한된 문서 불일치 | + +우선순위는 고치는 순서다. P1은 해당 용도 도입 전 해결, P2는 계획적 개선, P3는 선택이다. + +**확인 리뷰 — Critical / Important / Minor** (`superpowers:requesting-code-review` 리뷰어 지침의 체계) + +| 등급 | 정의 | +| --- | --- | +| Critical | 전체 리뷰의 Critical과 같다 | +| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자에게 틀린 조치를 시키는 문서 | +| Minor | 그 밖의 결함. 예: 거짓 실패 쪽 검사, 좁은 조건의 불일치, 문구 | + +확인 리뷰 발견에는 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. 이번 수정이 만든 것은 회귀로 따로 센다. + +**심각도가 정하지 않는 것** + +- 고칠지 말지. 이 repo는 모든 발견을 고치거나 결정으로 닫는다([improve.md](../improve.md) 4.5절). 심각도는 고치는 순서와, 맡긴 쪽이 코드에서 다시 확인할 범위(High·Important 이상)만 정한다. +- 건수. 한 결함이 여러 관점에 걸치면 항목 하나에 관점 번호를 모두 붙인다. 두 영역이 같은 결함을 적으면 색인에서 합친다. + +## 4. 증거 수준 E0~E4 (가이드 35.5절) + +| 수준 | 이 repo의 증거 | 주장할 수 없는 것 | +| --- | --- | --- | +| E0 설명·주장 | README, `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 실제 기동, 부하·장애 주입·동시 요청 실험 | 운영 환경, 운영 기간 | +| E4 운영 관찰 | 이 템플릿에는 없다 | — | + +- 이전 라운드의 실행 결과는 현재 증거가 아니다. 바뀐 커밋에서 다시 돌린다. +- 묶음 보고의 "통과"는 E0다. 맡긴 쪽은 보고를 diff와 실행 로그에 대조한다. +- build cache로 통과한 실행은 그렇다고 적는다. 실행 시간이 짧으면 캐시 재사용인지 확인한다. +- 발견마다 증거 수준을 적는다. 섞이면 나눠 적는다. 예: "E3 — 명령 9·10, 잠금 동작은 E1". + +## 5. 통제 수준 M0~M4 (가이드 35.4절) + +| 수준 | 뜻 | 이 repo의 예 | +| --- | --- | --- | +| M0 | 지킬 수단이 없다 | — | +| M1 | 적혀만 있다 | "하지 마라"가 주석·문서에만 있다 | +| M2 | 구현되어 있다 | 코드 경로에 규칙이 있고 검사는 없다 | +| M3 | 자동 검증이 위반을 잡는다 | ArchUnit(`src/app-bootstrap/src/architectureTest/`), 공유 계약 테스트, `verifyStrictLaneStages` | +| M4 | 경계에서 강제한다 | Gradle 의존 방향 게이트(`verifyCleanArchitectureDependencies`), DB 유일 제약, 기동 실패 rule | + +- 확인하지 못한 것은 M0가 아니라 "미확인"이다. +- 위반하면 데이터·권한이 깨지는 규칙이 M1이면 결함으로 적는다. + +## 6. 28개 관점 — 이 repo에서 볼 곳 + +관점의 일반 설명은 가이드 1~28절이다. 판정 기호: O 충족 · P 부분 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 종합은 평균하지 않는다. 한 영역이라도 X면 X다. + +| # | 관점 | 볼 곳 | 이런 증거면 결함 | +| --- | --- | --- | --- | +| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 | +| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `CLAUDE.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import | +| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 | +| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 | +| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 | +| 6 | 실패 성숙도 | 예외 분류, `retryable`, 결과 불명 | 결과 불명을 확실함으로, 재시도 가능을 확정 실패로 기록 | +| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/registries/metrics.yaml`, 종료 순서 | runbook이 틀린 조치를 시킴, 레지스트리 지표를 아무 코드도 내보내지 않음 | +| 8 | 디버깅 가능성 | `ServerFailureLog`, correlation id, 오류 코드 | 서버 실패를 남기지 않음, 원인이 다른 실패를 같은 코드로 | +| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석 | 갈라진 복사본, 현재 동작과 다른 주석·문서 | +| 10 | 테스트 성숙도 | 7절 | 이름의 성질을 단언하지 않음, 변이 생존, 계약 밖 fake | +| 11 | 데이터 성숙도 | 마이그레이션 스트림, 유일 제약, `@Version`, 잠금 시간 제한 | 중복 규칙에 DB 제약 없음, 적용된 마이그레이션 수정, `lock_timeout` 없는 강한 잠금 | +| 12 | 동시성 성숙도 | claim·lease, `SKIP LOCKED`, 트랜잭션 경계 | 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim | +| 13 | 확장성 | 연결·구독·동시 호출·본문 크기 상한 | 상한이 없거나 코드에 드러나지 않음 | +| 14 | 성능 성숙도 | 8절 | 데이터 수에 비례하는 SQL 수(N+1), 순차 스캔 | +| 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`, `src/Dockerfile.sample`, compose, `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서 | +| 19 | 설정 성숙도 | `StrictSettingsBinder`, `docs/registries/env-keys.yaml`, `config/module-defaults/<모듈>.yml`, `verifyEnvKeys` | 바인딩되지만 동작하지 않는 키, 한 설정을 두 곳에서 읽음 | +| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함 | +| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 | +| 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 | +| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 | +| 24 | 네이밍·의미 | `src/application-core/CLAUDE.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 | +| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 | +| 26 | Ownership | leaf마다 가까운 `CLAUDE.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 | +| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거, sample 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 | +| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 | + +**따라갈 시나리오** (가이드 31절). 전체 리뷰는 시나리오마다 요청 하나를 끝까지 따라가며 입력 신뢰 수준, 권한 판단 위치, 규칙 소유자, 트랜잭션 시작과 끝, 외부 부작용, 오류 변환을 적는다. 해당 기능이 없으면 적용 제외 사유를 한 줄 적는다. + +| 시나리오 | 따라갈 경로 | +| --- | --- | +| 정상 쓰기 요청 | sample `POST /api/worklogs`, 생성 명령으로 만든 기능 | +| 중복·동시 요청 | 같은 제목 동시 `POST /api/posters`, 멱등 키(`docs/manual/05-idempotency.md`) | +| 외부 응답 지연·유실 | httpclient 시간 예산·breaker, 알림 발송 attempt | +| DB 오류·경쟁 | `PersistenceExceptionTranslator`, `@Version`, 트랜잭션 마감 | +| 메시지 중복·역순 | outbox relay, inbox 재전달, aggregate 순서 번호 | +| 신·구 버전 공존 | 마이그레이션 잠금, 배포 중 섞인 인스턴스 | +| 여러 서버의 작업 실행 | 알림 정산 job claim, gRPC ledger claim | +| 다른 사용자 리소스 접근 | 파일 서버 소유자 검사, sample 소유자 검사 | +| 큰 입력·목록 조회 | `GET /api/worklogs?size=100`, GraphQL 복잡도, JSON 아닌 본문 | +| 종료·재시작 | relay·platform 종료 순서, 종료 시간 예산 | +| 선택 어댑터 제거 | `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄 제거 | + +## 7. 테스트가 증명해야 하는 것 + +정본: 테스트 작성 규칙은 `AGENTS.md` 「테스트 전략」, 테스트 분류·배치·source set은 `docs/testing/TESTING_STRATEGY.md`(기계 기준 `TestLaneCategory`), 새 기능의 테스트 배치는 `docs/manual/08-testing.md`다. + +| 점검 | 결함 모양 | +| --- | --- | +| 이름이 말한 성질을 단언하나 | 이름은 "X를 남기지 않는다"인데 준비가 다른 예외를 넣는다 | +| 부재 단언이 null과 "키 없음"을 구분하나 | `doesNotExist`가 null 필드도 통과 | +| 지키려는 코드를 지우면 실패하나(변이) | 검사를 지워도 전부 통과 | +| 시간 제한 대기의 반환값을 단언하나 | `CountDownLatch.await(timeout)` 결과를 버려 시간 초과에도 다음 단계로 감 | +| skip이 0이거나 설계 이유가 있나 | 계약 케이스가 조용히 skip | +| 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 위반 fixture만 있어 거짓 양성을 못 봄 | +| `// when`이 하나인가 | 두 동작을 한 테스트가 봄 | +| 테스트 코드도 정적 분석을 통과하나 | 게이트 밖에서 실패한 채 방치 | +| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언 | + +fake와 공유 계약: 포트마다 hand-rolled fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와 실제 adapter가 같은 추상 계약(`XxxContract`)을 상속한다. 계약 밖 fake, 소비자 없는 fake, 계약과 겹친 adapter 손 사본 테스트는 만들지 않는다. fake 동작을 바꾸면 계약 케이스를 같이 바꾼다. 포트를 더하거나 계약을 옮기면 `docs/testing/TESTING_STRATEGY.md`의 현황표를 고친다. + +lane: 새 lane은 반드시 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run`). 반드시 돌아야 하는 테스트는 `requires(클래스)` + `rejectSkipped`로 이름을 박는다. lane 정책 값은 Test 입력으로 선언한다. 저장소 파일을 읽는 테스트는 태그를 단다(문서와 대조하면 `document-contract`, 빌드 스크립트·workflow·compose를 읽으면 `repository-contract`). + +RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신에 따라 통과하지 않는다. 실 vendor가 필요한 결함은 실 vendor에서 본다(단위 테스트로 대신했으면 그렇게 적는다). 기록은 테스트 이름과 실패 수로 쓴다. + +## 8. 성능 측정 + +이 템플릿에는 지연·처리량 목표가 없다. 그래서 요청당 비용(SQL 수, 지연, 처리량, CPU)과 그 비용이 데이터 수에 비례해 늘어나는지로 판정한다. + +| 지표 | 재는 법 | 결함 신호 | +| --- | --- | --- | +| 아티팩트 | bootJar 크기, `BOOT-INF/lib` 목록 | 운영 jar에 테스트용·중복 라이브러리 | +| 기동 | `Started … in`, 기동 3초 뒤 RSS·heap, 빈 수, 스레드 수 | 빈 수에 비해 긴 공백 한 곳 | +| 요청당 SQL 수 | PostgreSQL `log_statement='all'`로 요청 하나 전후의 문장 수 | 페이지 크기에 비례(N+1) | +| 지연·처리량 | 닫힌 루프 부하, p50·p95·p99·rps | 목록 처리량이 SQL 수 비율만큼 떨어짐 | +| 요청당 CPU | JFR `settings=profile`, 상위 프레임 | 한 라이브러리가 CPU의 큰 몫 | +| 데이터 증가 | 같은 요청을 행 수를 늘려 반복 | 행 수에 비례해 느려짐 | +| 게이트 시간 | 게이트별 rc·초, 테스트 결과 XML 합계 | 바뀐 것이 없는데 매번 다시 도는 lane | + +측정 조건(전후가 같아야 비교할 수 있다): + +- 머신: 다른 빌드가 돌지 않는다. 측정 직전 1분 load average를 회차마다 적는다. 15를 넘은 회차는 비교에 쓰지 않는다. +- JVM: 옵션을 고정하고 적는다(예: `-Xmx1g -XX:+ExitOnOutOfMemoryError`). +- DB: 자원을 제한한 컨테이너(예: `--cpus 4 --memory 1g`), 튜닝 없음. +- 데이터: 행 수를 정해 적는다. 측정 중 늘어나는 테이블은 행 수를 함께 적는다. +- 부하: 닫힌 루프 N 스레드, 앞 20%는 워밍업으로 버린다. 생성기가 같은 호스트면 한계로 적는다. +- 반복: 3회, 중앙값. 튀는 회차는 이유와 함께 빼고 적는다. +- 설정만 바꾼 실험으로 원인을 먼저 확인한다(코드는 그대로, 시스템 프로퍼티 하나만). +- 측정은 E3다. "운영에서 N배 빨라진다"고 쓰지 않는다. 꼬리 지연의 원인을 확인하지 않았으면 미검증으로 적는다. + +최적화를 고르는 순서는 비용이 작은 것부터다: 설정 → DB(인덱스, 유일 제약, 쿼리 모양) → 매핑·쿼리 코드(N+1, 불필요한 컬렉션 재작성) → 구조(캐시, 비동기, 새 인프라). 캐시를 넣으면 무효화와 경합을 함께 검증한다. 고친 비용은 SQL 수처럼 머신과 무관한 숫자로 먼저 고정한다. + +## 9. 구조 기준과 leaf 변경 체크리스트 + +- 모듈 구조는 디렉터리가 아니라 registry가 정한다. 폴더를 바꾸는 일은 registry를 바꾸는 일이다. +- 문서는 leaf 목록·개수·leaf별 명령을 적지 않는다. leaf 명령은 registry의 `gradle_path`에서 만든다. +- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`). +- 템플릿 패키지 목록은 `src/application-core/CLAUDE.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다. +- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다. +- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.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`가 정본이다. + +leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼다: + +- [ ] `src/config/architecture/modules.json`: ID, `source_path`, `gradle_path`, `allowed_dependencies` +- [ ] 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」 표 +- [ ] ArchUnit 규칙과 그 위반·허용 fixture +- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다) +- [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행 + +검증은 [gates.md](gates.md) 2절의 "leaf 경계·의존·registry" 행이다. + +## 10. 리뷰 문서 양식 + +**위치**: 전체 리뷰는 `docs/reviews/-<종류>/README.md` + 영역 문서 `NN-<영역>.md`. 확인 리뷰는 그 폴더 아래 `roundN/`. 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고 처리 결과는 README에 적는다. + +**전체 리뷰 README의 절** (가이드 36.5절 양식에 처리 현황·결정 기록을 더한 것): + +1. 사용 결정 — 용도별 사용 가능·조건부·보류와 막는 항목 +2. 차단 항목(High·P1) — 맡긴 쪽의 재확인 방법을 칸으로 +3. 확인된 강점 +4. 반복되는 원인 — [defect-patterns.md](defect-patterns.md) 번호를 붙인다 +5. 결정이 필요한 것 — 선택지, 권고, 승인자 +6. 미검증 — 무엇, 왜, 확인하려면 +7. 개선 순서 — 순서, 대상, 이유, 완료 기준 +8. 재검토 조건 +9. 리뷰 범위 — 기준 커밋, 게이트 결과 표, 영역 표 +10. 28개 관점 판정 +11. 발견 색인 — ID, 심각도, 우선순위, 한 줄 내용. 모든 ID를 이름으로 적는다 +12. 이후 라운드 — 처리 표, 합칠 때 생긴 충돌과 처리, 합친 뒤 게이트, 결정, 남은 것 + +**영역 문서**: 범위 → 지난 발견 재확인 → 새 발견 → 시나리오 추적 → 설계 선택 검토(가이드 41절) → 리팩터링 후보 → 28개 관점 판정표. + +**확인 리뷰 문서**: + +| 절 | 적을 것 | +| --- | --- | +| 범위 | pathspec, `git diff --stat` 결과, 함께 읽은 주변 코드, 수정 보고의 「새로 가정하는 것」 | +| 불러온 스킬과 적용한 기준 | 스킬, 그 스킬의 기준, 그 기준으로 본 것 | +| 실행한 명령과 결과 | 명령, rc, 직전 1분 부하 | +| 못 본 것 | 무엇과 이유 | +| 항목 재확인 | 고쳤다고 한 항목마다 닫힘 / 부분 / 안 닫힘 | +| 결함 | `### · <심각도> · <한 줄 제목>` 아래 발견 필드 | +| Declined to judge | 판단하지 않은 것, 위치, 이유 | +| 결론 | Critical·Important·회귀 수, 결함 수와 "이번 수정 / 이전부터" 구분 | + +**발견 하나의 필드** + +- 전체 리뷰: 가이드 36.3절 표 필드 전체(성격, 관련 관점, 근거, 발생 조건, 영향, 심각도, 확실성, 결정의 근거, 이해 비용, 최소 개선 방향, 대안 비교, 단순화의 보존 조건, 비용, 재검토 조건, 완료 기준, 검증 방법). 선택 비교가 필요 없는 단순 결함은 설계 선택 필드를 `적용 제외 — <이유 한 문장>`으로 둔다. +- 확인 리뷰: 위치(`file:line`, 문서·설정·코드를 나눠서), 무엇이 틀렸나(한 문장에 사실 하나), 발생 조건·영향, 테스트가 못 본 이유, 고치는 법(권장안·대안·RED 테스트 모양), 이번 수정 / 이전부터, 증거(E 수준과 명령 번호). + +**ID** + +- 라운드 안에서는 `NN-MM`(영역-순번)이다. 확인 리뷰는 라운드 접두어를 붙여 `RR-NN-MM`으로 쓴다(첫 재리뷰만 `` 없이). +- 라운드 밖(다른 문서, 커밋, 주석)에서는 리뷰 폴더 날짜의 월일을 붙인다: `MMDD/`(가이드 36.3절). +- 영역 번호 자리에 `NN` 같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다. +- ID는 리뷰 문서·brief·커밋에서 쓴다. 매뉴얼(`docs/work/`) 본문에는 쓰지 않는다. + +## 11. 판단을 적는 법 + +- 판단 발견(설계·구조·비용)은 반증할 수 있는 가정과 반론을 함께 적는다. "이 판단이 틀렸다면 어디서 드러나나"를 쓴다. +- 결정적 발견(컴파일 오류, 의존 위반, 비밀 노출, 실패한 테스트)은 규칙 → 증거 → 고치는 법 세 줄로 쓴다. 억지 반론을 만들지 않는다. +- 대안이 3~5개 있으면 그만큼 비교한다. 실제로 더 적으면 적게 쓴다. 의존 순서가 있는 변경은 의존 그래프 순서로 따진다. +- 인용 확인은 리뷰 수준에 따른다: `review-lite`는 확인하지 않는다, `review-standard`는 차단 발견의 인용을 확인한다, `audit-deep`·`regulated`는 결론에 쓰인 인용을 모두 확인한다. +- 리뷰 결과를 문서 파일로 남기는 경우: 위험이 높다, 차단 발견이 3건 이상이다, 아키텍처 결정이 있다, 요청자가 원한다, `regulated` 수준이다. 그 밖에는 짧은 결과 보고로 충분하다. + +## 12. 리뷰어가 하지 않는 것 + +- 코드를 고치지 않는다. 실험은 별도 worktree에서 하고 지운다. +- 이전 실행 결과를 현재 증거로 쓰지 않는다(4절). +- 같은 결함을 여러 번 세지 않는다(3절). +- 정한 결정을 결함으로 다시 올리지 않는다. 결정의 전제가 틀렸다는 새 증거가 있을 때만 근거와 함께 다시 연다([decisions.md](decisions.md) 1절). +- 범위 밖 결함을 버리지 않는다. 「Declined to judge」에 위치와 함께 적어 맡긴 쪽에 넘긴다. diff --git a/docs/work/research-design.md b/docs/work/research-design.md new file mode 100644 index 00000000..de9d32a8 --- /dev/null +++ b/docs/work/research-design.md @@ -0,0 +1,90 @@ +# 조사·설계 — 바꾸기 전에 대안을 비교하고 결정을 받는다 + +코드를 바꾸기 전에 무엇을 할지 정하는 일이다. 사고 순서(목적 → 선행 사례 → 방법 → 필요한 정보 → 격차 → 만들고 시험)의 정본은 design-docs `conventions/work-thinking-order.md`다. 이 playbook은 순서를 다시 쓰지 않고, 이 repo에서 어디를 보고 결과를 어디에 두는지만 정한다. + +## 1. 언제 쓰나 + +- 고치거나 만들기 전에 소유자 결정이 필요하다(공개 계약, 파생 서비스 동작, 보안 정책, 새 leaf, 되돌리기 비싼 선택). +- 리뷰가 "판단하지 않음"으로 남긴 항목을 어떻게 닫을지 정해야 한다. +- 큰 일의 1~5단계와 대안 비교를 소유자 검토용으로 만든다. +- 설계 메모 하나를 쓴다(예: 레지스트리의 칸 하나를 규범으로 둘지). +- 결정이 이미 [reference/decisions.md](reference/decisions.md)에 있으면 이 playbook이 아니다. 그 결정대로 [improve.md](improve.md)나 [new-feature.md](new-feature.md)로 간다. + +## 2. 받아야 할 것 + +- 정할 질문 한 문장과 누가 왜 묻는가(요청 원문). +- 크기와 결정할 사람. 큼이면 소유자 검토가 만들기 전에 있어야 한다. +- 산출물 위치(4절 6단계 기준과 다르면 brief를 따른다). +- 코드를 바꿔도 되는지. 기본은 바꾸지 않는다. + +## 3. 크기와 사고 순서 + +- 설계 메모 하나는 보통 중간이다: 선행 사례 2~3곳(내부 선례 포함), 대안 2~3개. +- 새 체계·아키텍처·공개 계약은 큼이다: 선행 사례 10~15곳, 대안 3~5개. 1~5단계 결과와 대안 비교를 소유자가 먼저 본다. +- 이 repo의 내부 선례를 찾는 곳: + - [reference/decisions.md](reference/decisions.md)와 그 출처 문서 + - `docs/reviews/`의 리뷰 README 「결정」 절과 영역 문서의 「Declined to judge」 + - `docs/adr/`(되돌리기 비싼 선택), `docs/superpowers/specs/`(설계서), `docs/superpowers/plans/`(계획서) + - `git log --oneline -- <경로>`와 커밋 본문의 "고른 방법과 버린 대안" + - 가장 가까운 `src/**/CLAUDE.md`와 모듈 README +- 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(Spring Boot, Flyway, Hibernate 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다. +- 스킬: `superpowers:brainstorming`, 결정 기록은 `documentation-and-adrs`, 공식 문서 확인은 `source-driven-development`. 큰 판단은 `doubt-driven-development`로 반론을 세운다. + +## 4. 절차 + +1. 목적을 한 문장으로 적고 성공 기준을 정한다. 요청 원문이 있으면 인용한다. +2. 이미 정한 것을 찾는다(3절의 내부 선례). 이미 정해져 있으면 멈추고 그 결정을 보고한다. +3. 현황을 확인한다. 주장마다 출처를 단다: `file:line`, 커밋, 명령 결과. 실제 동작이 궁금하면 별도 worktree에서 탐침 테스트를 desktop으로 돌리고, 탐침 코드는 남기지 않는다. +4. 선행 사례 표를 만든다: 출처 · 1차/2차 · 그들이 한 것 · 실패와 비판 · 가져올 것. +5. 대안을 비교한다. 실제로 다른 대안 2~5개(크기에 맞게), 기준(효과, 비용, 되돌리기, 파생 서비스 영향, 기존 결정과 충돌), 권하는 안과 이유. 의존 순서가 있는 변경은 의존 그래프 순서로 따진다. +6. 반증할 수 있는 가정을 적는다: "이 안이 틀렸다면 어디서 드러나나". 반론과 답도 적는다. +7. 산출물을 둔다. + - 이 repo에만 해당: 설계서 `docs/superpowers/specs/-<주제>-design.md`, 되돌리기 비싼 선택이면 `docs/adr/ADR-<영역>-<번호>-<제목>.md`(기존 번호를 잇는다). + - 여러 repo나 소유자 운영에 걸침: design-docs. 템플릿 `docs/`는 파생 서비스로 복사되므로 로드맵·운영 설계는 여기에 두지 않는다. + - 짧은 설계 메모는 보고 본문으로 충분하다(brief가 파일을 요구하지 않으면). +8. 소유자 결정 목록을 쓴다: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람. 한 번에 묻는다. +9. 멈추고 검토를 받는다. 승인을 받으면 승인 시각을 적는다. +10. 결정을 기록한다([reference/decisions.md](reference/decisions.md) 3절). 만들기는 [new-feature.md](new-feature.md)나 [improve.md](improve.md)로 넘긴다. + +## 5. 완료 기준 + +- 보고에 사고 순서 흔적이 있다. 크기에 맞는 단계가 있고, 생략한 단계는 이유가 한 줄 있다. +- 사실마다 출처(`file:line`, 커밋, 명령 결과)가 있다. 추정은 추정이라고 적었다. +- 대안 비교 표, 권하는 안, 반증할 수 있는 가정이 있다. +- 소유자 결정 목록이 있고, 질문을 보냈거나 승인 시각이 있다. +- brief가 허용하지 않았으면 코드가 바뀌지 않았다(`git diff --stat`에 문서만). + +## 6. 하지 말 것 + +- 소유자 검토 전에 만들지 않는다. 큰 일은 1~5단계와 대안 비교까지만 하고 멈춘다. +- 크기를 스스로 내리지 않는다. +- 이미 정한 결정을 다시 묻지 않는다. 다시 열 조건은 [reference/decisions.md](reference/decisions.md) 1절이다. +- "업계 표준이다", "추상화가 많다" 같은 말을 근거로 쓰지 않는다. 이 repo의 어느 계약·비용에 닿는지로 쓴다. +- 대안을 하나만 놓고 권하지 않는다. +- 탐침 코드를 제품 코드에 남기지 않는다. + +## 7. 막혔을 때 + +- 필요한 정보가 이 repo와 공개 자료에 없으면(운영 수치, 소유자의 계획) 그 칸을 "모름"으로 두고 질문 목록에 넣는다. +- 질문은 한 번에 모아 보낸다. 형식은 [README](README.md) 5절이다. 답이 올 때까지 그 결정에 기대는 단계만 멈춘다. + +## 8. 보고 형식 + +[README](README.md) 6절에 더해 적는다. + +```markdown +## 결론 (권하는 안 한 문장) +## 사고 순서 흔적 (크기: 중간) +1. 목적: 2. 선행 사례: 3. 방법: 4. 필요한 정보: 5. 격차: 6. 만들고 시험: +## 대안 비교 +| 대안 | 효과 | 비용 | 되돌리기 | 기존 결정과 충돌 | +## 반증할 수 있는 가정 / 반론과 답 +## 소유자가 정할 것 +| 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 | +``` + +## 9. 자주 하는 실수 + +- 정리한 글(2차)을 원문처럼 인용한다. 원문을 찾아 확인하고 1차/2차를 표시한다. +- 지난 리뷰의 결정을 찾지 않아 같은 질문을 다시 한다. 결정 색인과 리뷰 README 「결정」 절부터 본다. +- 조사하다 바로 고친다. 고치는 일은 결정 뒤에 다른 playbook으로 한다.