docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다

문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.

고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
  → docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
  원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.

옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.

위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.

검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
This commit is contained in:
DongHyeonka
2026-11-07 12:15:45 +09:00
parent ac03192ddd
commit 630f9b860a
282 changed files with 119 additions and 80 deletions
+4
View File
@@ -18,3 +18,7 @@ src/.env.lane
graphify-out/
src/graphify-out/
.playwright-mcp/
# Python bytecode from running scripts/ checks; never committed.
__pycache__/
*.pyc
+3 -3
View File
@@ -171,8 +171,8 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
1. 요구사항을 읽고 소유 계층을 판단한다.
2. 구조나 동작이 바뀌면 `superpowers:brainstorming`으로 설계를 먼저 확정한다.
3. 여러 단계의 작업이면 `docs/superpowers/specs/`에 설계 문서를 남긴다.
4. 구현 전 `docs/superpowers/plans/`에 실행 계획을 작성한다.
3. 여러 단계의 작업이면 `docs/design/`에 설계 문서를 남긴다. 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다.
4. 실행 계획이 필요하면 구현 전 `docs/history/plans/`에 둔다. 계획서도 머리 블록을 단다. 머리 블록 형식은 `docs/README.md`다.
5. 동작 변경은 테스트를 먼저 작성한다.
6. 새 비즈니스 개념은 `domain-core`에 먼저 둔다.
7. 유스케이스는 `application-core` command와 use case/service method로 표현한다.
@@ -249,7 +249,7 @@ leaf의 `check`는 그 leaf만 검사한다. 저장소 전체 질문은 이름
Redis, Kafka, JPA 같은 부가 기능은 "의존성을 붙이면 켜지고, 떼면 사라지는 모듈"로 제공한다.
각 서비스는 `app-bootstrap/build.gradle`에 필요한 모듈만 `runtimeOnly` 한 줄로 고른다.
설계 근거는 `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md`.
설계 근거는 `docs/design/2026-09-25-capability-module-packaging-design.md`.
템플릿 기본 조립은 web에서 쓰는 부분뿐이다: `adapter:inbound:web`, 운영 관측(actuator·metrics·
tracing·로그), `domain-core`·`application-core`·`shared-contract`, `adapter:outbound:support`·
+1 -1
View File
@@ -63,7 +63,7 @@ brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이
- **성능 lane에는 단언을 끄는 스위치가 없다.** convention이 상한을 매번 단언하고, `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(`AGENTS.md` 「Gradle 정책 권위」).
- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow를 읽는 테스트는 `repository-contract`(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다.
- **커밋 정책은 `human-only`다.** brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다.
- **문서 위치 규칙은 [docs/README.md](docs/README.md)다.** 설계서는 `docs/superpowers/specs/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다.
- **문서 위치 규칙은 [docs/README.md](docs/README.md)다.** 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 고치지 않는 기록(계획서·납품 패키지·증거·학습)은 `docs/history/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다. 기록은 맨 위 머리 블록만 고친다.
## 6. 소유자 환경
+12 -7
View File
@@ -26,23 +26,28 @@
| `architecture/` | 공개 API 표면 스냅숏 |
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 |
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` |
| `evidence/` | 작업 단계별 증거·체크포인트 |
| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT |
| `reviews/` | 모듈 코드 리뷰 결과 |
| `runbooks/` | 장애 코드별 대응 런북 (`template.md` 기준) |
| `security/` | 공개 경로 스냅숏 |
## 설계와 계획
## 설계와 기록
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
| 디렉터리 | 대상 |
| --- | --- |
| `superpowers/specs/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
| `superpowers/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
| `superpowers/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
| `history/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
| `history/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
| `history/evidence/` | 작업 단계별 증거·체크포인트 |
| `history/study/` | 학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 |
`superpowers/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `specs/` 와 `plans/` 에 있으므로 이 디렉터리에서
`history/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/` 과 `history/plans/` 에 있으므로 이 디렉터리에서
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256` 은
납품 당시 바이트의 해시다.
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는
+1 -1
View File
@@ -71,7 +71,7 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
복구가 필요하면 표의 커밋에서 경로를 꺼낸다(`git show <커밋>:<경로>`).
리뷰 후속 작업(2026-09-25~28, `docs/superpowers/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다.
리뷰 후속 작업(2026-09-25~28, `docs/history/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다.
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
| --- | --- | --- | --- |
+1 -1
View File
@@ -19,7 +19,7 @@
| `:app-bootstrap:sampleOffTest`, `ci-quality-gates.yml`의 `sample-off` job | sample 픽스처를 지워도 애플리케이션이 빌드·부팅되는가 |
| `sample-portfolio` leaf 전체 | 참조 구현 |
| `Dockerfile.sample`, `docker-compose.*` 중 sample 관련 | 위와 동일 |
| `docs/superpowers/**` | 이 템플릿을 만든 과정의 설계/계획 기록 |
| `docs/design/**`, `docs/history/**` | 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록 |
| `gradle/qualification/**` | 이 템플릿이 벤더링한 플랫폼(JPA, messaging)의 인증 체계 |
| `*-certification.yml`, `*-qualification.yml`, `jpa-next-*.yml` | 템플릿이 광고하는 지원 매트릭스의 근거 |
@@ -114,7 +114,7 @@ native provenance.
**Mode B — controlled reconstruction.** The original source is unavailable or incomplete. The
human records that fact and explicitly authorizes reconstruction from the approved
[`2026-07-20-harness-policy-engine-design.md`](2026-07-20-harness-policy-engine-design.md),
[`2026-07-20-harness-policy-engine.md`](../plans/2026-07-20-harness-policy-engine.md), the tracked
[`2026-07-20-harness-policy-engine.md`](../history/plans/2026-07-20-harness-policy-engine.md), the tracked
Gradle/module sources, and this design. Reconstructed artifacts receive new hashes and a
`controlled-reconstruction` provenance record. Schema, renderer parity, mutation coverage, Gradle
project discovery, and architecture dependency checks must pass before the new artifacts can act as
@@ -952,7 +952,7 @@ and durable interfaces are explicit.
The authoritative implementation-level design for this capability is
[Object Storage Production Capability Deep Design](2026-07-28-objectstorage-production-capability-design.md).
Its ordered RED–GREEN execution batches and promotion gates are in the
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md).
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md).
This subsection is only the cross-capability baseline; the dedicated design governs when details
differ.
@@ -15,7 +15,7 @@
이 문서는 Notification capability의 승인된 상세 설계다. 2026-07-28에 §36의 다섯 gate를
사용자가 승인했으며, 실제 구현 순서는
[Notification Production Capability Implementation Plan](../plans/2026-07-28-notification-production-capability.md)을
[Notification Production Capability Implementation Plan](../history/plans/2026-07-28-notification-production-capability.md)을
정본으로 사용한다. 구현 및 production readiness는 아직 주장하지 않는다.
2026-07-28 현재 구현된 범위:
@@ -4793,7 +4793,7 @@ COMPLETE 뒤 reverse가 필요하다면 canonical in-flight/intent backlog/provi
inbound messaging/inbox architecture로 설계를 수정해야 한다.
사용자는 2026-07-28에 위 다섯 결정을 승인했다. 구현은
[Notification Production Capability Implementation Plan](../plans/2026-07-28-notification-production-capability.md)의
[Notification Production Capability Implementation Plan](../history/plans/2026-07-28-notification-production-capability.md)의
작은 TDD task, owner leaf, registry-derived Gradle path, focused test, architecture gate,
real-provider evidence와 rollback point를 따른다.
@@ -12,7 +12,7 @@
- 상위 문서:
[Production Capability Platform Design](2026-07-26-production-capability-platform-design.md)
- 구현 계획:
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md)
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md)
- 참고 설계:
[Redis Production Capability Deep Design](2026-07-26-redis-production-capability-design.md),
[Fileserver Production Capability Deep Design](2026-07-26-fileserver-production-capability-design.md),
@@ -78,11 +78,11 @@
create-only PUT/complete 조건을 무시하므로 managed/direct mutation profile을
`UNSUPPORTED`로 유지하며 readiness를 올리지 않는다.
증거는 [Batch A checkpoint](../../evidence/object-storage/batch-a-checkpoint.md),
[Batch B checkpoint](../../evidence/object-storage/batch-b-checkpoint.md),
[Batch C checkpoint](../../evidence/object-storage/batch-c-progress.md),
[Batch D checkpoint](../../evidence/object-storage/batch-d-checkpoint.md),
[Batch E pause checkpoint](../../evidence/object-storage/batch-e-pause-checkpoint.md)에 기록했다.
증거는 [Batch A checkpoint](../history/evidence/object-storage/batch-a-checkpoint.md),
[Batch B checkpoint](../history/evidence/object-storage/batch-b-checkpoint.md),
[Batch C checkpoint](../history/evidence/object-storage/batch-c-progress.md),
[Batch D checkpoint](../history/evidence/object-storage/batch-d-checkpoint.md),
[Batch E pause checkpoint](../history/evidence/object-storage/batch-e-pause-checkpoint.md)에 기록했다.
격리 브랜치에서는 private vault 경로를 잘못 선택해 capture가 차단됐지만, main 통합 작업은
사용자가 지정한 public vault의
@@ -4015,7 +4015,7 @@ authorization endpoint의 ephemeral response이며 stored object DTO에 영구
## 37. 구현 계획 작성 전 확정 항목
정본 구현 순서와 아래 결정의 현재 freeze/approval gate는
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md)에
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md)에
기록한다. Tasks 1–24의 구현은 Batch E pause checkpoint까지 진행됐지만 Batch E 전체
combined/root gate는 아직 통과하지 않았다. Tasks 25–30은 미착수다. 이 구현 진행이나
계획 승인이 public API, scanner provider 또는 AWS/IaC 외부 변경 권한을 자동으로 부여하지

Some files were not shown because too many files have changed in this diff Show More