Files
clean-architecture-backend-…/docs/manual/README.md
T
DongHyeonka 81ef58ab17 docs(manual): 본문에 남은 이력 ID 19줄을 내용과 날짜로 바꾼다
문제: docs/manual 본문 19줄이 "리뷰 02-01 결정", "1라운드 06-01·06-03",
"리뷰 README 13.2, 09-02", "(05-01, 04-01, 06-01)", "sample P30 결정"처럼
지난 리뷰 번호만으로 이유를 댄다. 그 리뷰를 모르는 독자는 따라갈 수
없고, docs-writing.md 4절 6단계가 금지한다. 16줄은 --history 검사가
찾았고, 3줄은 걷어낸 뒤 grep으로 다시 읽어 찾았다.

고른 방법: 문장의 뜻은 두고 괄호만 바꾼다.
- 문장이 이미 내용을 말하는 곳(6줄)은 괄호를 지운다
- 지난 일이 근거인 곳은 날짜와 일어난 일로 바꾼다. 예: "2026-11-01
  소유자 결정", "2026-11-01부터. 전에는 비어 있으면 검증을 건너뛰었다"
- README 제목 "1라운드 수정으로 생긴 패턴 (리뷰 README 13절)"은
  "리뷰 뒤 첫 수정으로 생긴 패턴"으로 바꾼다. 이 제목을 가리키는 링크는
  repo에 없다
걷어낸 번호와 원래 괄호, 원래 리뷰 문서와 발견 내용은
docs/work/evidence.md 8절에 표로 더했다(2026-11-06 표와 같은 칸).
버린 대안: 리뷰 문서로 링크 걸기. 본문이 다시 이력을 가리킨다.

위험·한계: 날짜와 "전에는" 문장은 1101 README 13절·15절과 영역 문서의
색인 문장에서 옮겼다. 코드로 다시 확인하지는 않았다. evidence.md 9절
T4-1 행("16줄은 고치지 않음")은 그때의 기록이라 고치지 않았다.

검증(desktop worktree, 이 커밋과 같은 트리 8ff82a67):
- python3 scripts/check-work-docs.py --history docs/manual
  lines with history IDs: 0, rc=0
- python3 scripts/check-work-docs.py rc=0(분량, 본문 이력 0, 링크)
- python3 scripts/check-work-docs.py --links docs/manual docs/work
  링크 113개, 깨진 것 0
- ./gradlew :app-bootstrap:documentContractTest rc=0, 22개 클래스
  66건 통과, 실패·skip 0. docs/manual과 docs/work를 읽는 테스트는 없다
  (src의 Java·Gradle에서 파일 이름·폴더 경로 grep, 주석 2곳만 걸림)
- grep -e 리뷰 -e 라운드 -e 결정 docs/manual/*.md로 남은 줄을 읽었다.
  모두 날짜와 내용이 있는 문장이다
2026-11-07 00:25:32 +09:00

86 lines
7.3 KiB
Markdown

# 개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점
이 매뉴얼은 **새 업무 기능을 추가하는 사람**이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다
무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 **가리키고**
작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).
입구는 작업 매뉴얼의 [새 기능 playbook](../work/new-feature.md)이다. 일의 크기, 완료 기준, 하지 말 것은
거기에 있다. 새 기능이 아닌 일(개선, 조사·설계, 문서, 운영)은 [docs/work/](../work/README.md)가 맡는다.
판단 지점은 모두 같은 틀로 적는다.
- **고르는 기준** — 무엇을 보고 고르는가
- **기본값** — 기준이 애매하면 이것
- **예외** — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것
근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.
## 읽는 순서
처음이면 1 → 2 → 3을 읽고 생성 명령을 한 번 돌려 본다. 그다음은 기능에 필요한 장만 읽는다.
| 장 | 언제 읽나 |
| --- | --- |
| [01. 생성 명령](01-generator.md) | 새 기능 뼈대를 만들 때. 무엇을 만들고 무엇을 안 만드는지 |
| [02. 새 도메인·유스케이스 추가](02-new-feature.md) | 기능 하나를 domain → application → outbound → inbound → bootstrap 순서로 만들 때 |
| [03. 새 기능을 둘 곳 고르기](03-placement.md) | 계층 leaf 안 패키지 / `application-*` capability / 별도 수직 중 고를 때 |
| [04. 영속성](04-persistence.md) | 저장 adapter, 엔티티 매핑, DB 제약과 충돌 변환, 마이그레이션 번호 |
| [05. 멱등성·결과 불명](05-idempotency.md) | 재시도될 수 있는 쓰기, 409/422, `DB_COMPLETION_UNKNOWN` |
| [06. 오류 모델](06-errors.md) | 실패를 클라이언트 탓/서버 탓으로 나누고 코드로 내보낼 때 |
| [07. 권한](07-authorization.md) | `@RequiresPermission`, 역할 매핑, 객체 단위 인가 |
| [08. 테스트 작성 규칙](08-testing.md) | 포트당 fake, 공유 계약, 이름·주석, lane 단계 지정 |
| [09. outbox·이벤트](09-outbox-events.md) | 저장과 함께 이벤트를 내보낼 때 |
| [10. capability 추가·제거](10-capabilities.md) | JPA·Redis·Kafka 같은 부가 기능을 켜고 끌 때 |
| [11. 체크리스트](11-checklist.md) | PR 올리기 전 |
| [부록. 공통 원칙 후보](appendix-common-principles.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」 |
| HTTP wire 계약(Envelope·멱등성 응답) | `docs/web/http-contract.md` |
| 운영 오류 코드 | `docs/registries/error-codes.yaml`, `src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java` |
| 엔티티 매핑·마이그레이션 | `docs/jpa/entity-mapping-guide.md`, `docs/jpa/migration-guide.md`, `docs/jpa/transaction-guide.md` |
| capability 완료 기준 7개 | `AGENTS.md` 「부가 기능(capability) 모듈 규칙」 |
이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 **따른 결과**를 보여 줄 뿐이고,
규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(`scripts/feature-scaffold/templates/`)이 규칙과
어긋나면 `scripts/verify-feature-scaffold.sh`가 ArchUnit으로 잡는다.
## 따라 할 예시는 하나
예시가 셋(sample-portfolio 수직, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라
배치가 달라졌다(2026-11-01 성숙도 리뷰). 이제 **새 업무 기능의 예시는 생성 명령의 출력 하나**다.
| 코드 | 역할 | 따라 하나 |
| --- | --- | --- |
| `scripts/new-feature.sh` 출력 | 계층 leaf에 나눈 업무 기능 | **이것을 따른다** |
| `src/sample-portfolio` | 한 leaf에 모든 계층을 둔 지울 수 있는 샘플. 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일성 제약)의 참고 | 기법만 본다. 배치는 따르지 않는다 |
| `src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/**` | ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 |
| `application-core/.../operation` + `DurableOperationAutoConfiguration`(composition:durable-operation) | 템플릿 플랫폼 기능 | 조립 모양(`@ConditionalOnBean` + 유스케이스 `@Bean`)만 본다 |
## 리뷰 뒤 첫 수정으로 생긴 패턴
2026-11-01 성숙도 리뷰 뒤 같은 날 한 첫 수정에서 굳은 모양이다. 각 장에 반영했다.
| 패턴 | 근거 코드 | 장 |
| --- | --- | --- |
| Envelope는 null 필드를 내보내지 않는다 | `docs/web/http-contract.md` 1절 | 06 |
| 처리 중 409 `IDEMPOTENT_IN_FLIGHT`는 `retryable=true` + `Retry-After: 2`, 같은 키로 재전송 | `docs/web/http-contract.md` 2절 | 05 |
| 커밋 중 연결이 끊기면 재시도 가능이 아니라 결과 불명(`DB_COMPLETION_UNKNOWN`, 500) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java`, `docs/adr/ADR-JPA-003-completion-unknown.md` | 05 |
| 중복 규칙은 조회 후 insert가 아니라 DB 유일성 제약, 위반은 같은 409로 변환 | `src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql`, `PosterRepositoryAdapter` | 04 |
| 여러 인스턴스가 집는 작업은 lease 있는 claim | `ReconciliationJobStorePort.claimDue`(application-notification) | 04 |
| 양방향 연관관계 금지를 ArchUnit으로 | `JpaArchitectureRules.associationsAreMappedFromOneSideOnly()` | 04 |
| store는 호출자 트랜잭션을 요구한다 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java` | 04 |
| `@RequiresPermission` 검사는 인증 체인과 분리된 자동 설정 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java` | 07 |
| JWT audience 필수, 자기 client role만 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/JwtDecoderConfig.java`, `docs/runbooks/auth-audience-mismatch.md` | 07 |
| strict lane은 반드시 어떤 단계에 속한다 | `verifyStrictLaneStages`(`src/build.gradle` `strictLaneStages`) | 08 |
| 샘플 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 | `SamplePostgreSqlPersistenceConfig`, `V8_1__…` | 04 |
| 재시도 가능한 broker 거부는 DEAD가 아니라 재시도 | `docs/runbooks/outbox-dead-letter.md` | 09 |