docs(work): 넘친 operate.md와 재배치 뒤 낡은 지침을 고친다 #16
@@ -18,9 +18,9 @@ Gradle·Docker는 desktop에서만 돈다. 절차의 정본은 `docs/work/operat
|
||||
|
||||
1. desktop에 따로 worktree를 만든다. 기존 checkout `~/workspace/clean-architecture-backend-template`의 브랜치와 `stash@{0}`는 건드리지 않는다.
|
||||
2. 로그 폴더 `~/<작업 이름>-logs/`를 만들고 `uptime`으로 부하를 본다.
|
||||
3. worktree 루트에서 `flock /tmp/claude-gates/heavy.lock scripts/bootstrap-local.sh > ~/<작업 이름>-logs/bootstrap.log 2>&1; echo "rc=$?"`를 돌린다. 스크립트가 컴파일 → DB 기동 → 앱 기동 → health 200과 `status=UP`을 차례로 본다.
|
||||
3. worktree 루트에서 `scripts/verify.sh app --on here > ~/<작업 이름>-logs/bootstrap.log 2>&1; echo "rc=$?"`를 돌린다. `verify.sh`가 공유 잠금을 잡고 Gradle daemon을 끈 채 `scripts/bootstrap-local.sh`를 부른다. 스크립트가 컴파일 → DB 기동 → 앱 기동 → health 200과 `status=UP`을 차례로 본다.
|
||||
4. 앱이 떠 있는 동안 받은 endpoint를 `curl --silent --show-error --max-time 5 --write-out '\n%{http_code}'`로 부르고 응답을 로그 폴더에 남긴다.
|
||||
5. 저장소 루트에서 `docker compose --profile '*' down`으로 내린다. 컨테이너가 만든 root 소유 폴더가 남으면 4.1절의 정리법을 따른 뒤 worktree를 지운다.
|
||||
5. 저장소 루트에서 `docker compose --profile '*' down`으로 내리고 `git worktree remove`로 worktree를 지운다. 지우지 못하면 「남은 것」에 적는다.
|
||||
|
||||
## 돌려줄 것
|
||||
|
||||
|
||||
@@ -65,7 +65,7 @@ paths:
|
||||
|
||||
## 검증
|
||||
|
||||
Gradle은 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은 `src/`에서다.
|
||||
Gradle은 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은 저장소 루트에서다.
|
||||
|
||||
- API surface: leaf `check` 안의 `verify<Label>ApiSurface`(PR 단계). 의도한 변경이면 리뷰 뒤 `update<Label>ApiSurface -Papprove<Label>ApiSurfaceChange`.
|
||||
- 공개 경로: `./gradlew verifyPublicPathSnapshot`(`mainCheck`·`releaseCheck` 안에도 있다).
|
||||
|
||||
@@ -54,7 +54,7 @@ paths:
|
||||
|
||||
## 검증
|
||||
|
||||
Gradle은 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은 `src/`에서다.
|
||||
Gradle은 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은 저장소 루트에서다.
|
||||
|
||||
- leaf: `scripts/verify.sh leaf :domain-core`, `scripts/verify.sh leaf :application-core`(도메인 테스트는 Spring 없는 순수 JUnit).
|
||||
- 경계: `./gradlew architectureCheck`(의존 방향, domain-core·shared-contract·application 순수성), `./gradlew :app-bootstrap:architectureTest`(`NamingConventionTest`, `ApplicationBoundaryArchitectureTest`, `DomainPurityArchitectureTest`).
|
||||
|
||||
@@ -76,7 +76,7 @@ paths:
|
||||
|
||||
## 검증
|
||||
|
||||
모두 desktop에서 돈다(`docs/work/operate.md` 4.1절). 노트북에서는 `scripts/verify.sh`로 보낸다. 명령은 `src/`에서다.
|
||||
모두 desktop에서 돈다(`docs/work/operate.md` 4.1절). 노트북에서는 `scripts/verify.sh`로 보낸다. 명령은 저장소 루트에서다.
|
||||
|
||||
- leaf: `scripts/verify.sh leaf :adapter:outbound:persistence-jpa`. 서비스 persistence leaf면 registry의 `gradle_path`를 쓴다.
|
||||
- 마이그레이션을 바꿨으면: persistence-jpa `check`(`MigrationLockWaitTest` 포함), `:adapter:outbound:persistence-jpa:postgresqlMigrationLockWaitIntegrationTest`, `:adapter:outbound:persistence-jpa:postgresqlMigrationIntegrationTest`, `:adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest`, `:adapter:outbound:persistence-jpa:jpaPlatformMigrationTest`. — `docs/work/reference/gates.md` 2절
|
||||
|
||||
@@ -75,7 +75,7 @@ paths:
|
||||
|
||||
## 검증
|
||||
|
||||
Gradle·Docker는 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은 `src/`에서다.
|
||||
Gradle·Docker는 desktop에서 돈다(`docs/work/operate.md` 4.1절). 명령은 저장소 루트에서다.
|
||||
|
||||
- 공개 경로·보안 체인을 바꿨으면 `./gradlew verifyPublicPathSnapshot`. 스냅숏 갱신은 리뷰 뒤 `-PapprovePublicPathChange`. — `docs/work/reference/gates.md` 2절
|
||||
- JWT·JWKS·CORS 경계: `:adapter:inbound:web:webSecurityBoundaryTest`(skip 거부), 오류 디스패치는 `JwtChainErrorDispatchIT`(web `systemTest`).
|
||||
|
||||
@@ -5,6 +5,6 @@
|
||||
- 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다.
|
||||
- 공통 훅·스킬(되돌릴 수 없는 명령 차단, 비밀 값 알림, 장부, `estimate`·`retro`·`techdebt`)은 하네스 플러그인 `harness@claude-harness`다(같은 settings가 켠다). 비대화형(`claude -p`)은 설치하지 않으니 claude-harness README의 `--scope project` 두 명령을 한 번 돌린다.
|
||||
- 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다.
|
||||
- 스킬은 `.claude/skills/`다: `new-feature`(새 기능), `desktop-gates`(Gradle·Docker를 desktop에서), 분야 지식 `be-*` 10개(`paths`가 걸려 그 분야 파일을 만질 때 목록에 뜬다). 여러 분야면 플러그인 `lead`. 발동 조건이 설명에 있어 모델이 부른다.
|
||||
- 스킬은 `.claude/skills/`다: `new-feature`(새 기능), `desktop-gates`(Gradle·Docker를 desktop에서), 분야 지식 `be-*`(`paths`가 걸려 그 분야 파일을 만질 때 목록에 뜬다). 여러 분야면 플러그인 `lead`. 발동 조건이 설명에 있어 모델이 부른다.
|
||||
- 서브에이전트는 `.claude/agents/`다: `reviewer`(렌즈로 받은 `be-*` 스킬로 새 창에서 diff 판정), `arch-reviewer`(구조 리뷰), `verify-api`(desktop에서 앱 띄워 확인), `code-simplifier`(단순화 제안). 모두 결과만 돌려주고 파일을 고치지 않는다.
|
||||
- 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다.
|
||||
|
||||
+2
-2
@@ -184,8 +184,8 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
|
||||
|
||||
## 문서 검사
|
||||
|
||||
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 workflow `docs-check`가
|
||||
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
|
||||
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 `pr.yml`의 `done` job이 `./gradlew :prCheck`
|
||||
안의 `documentCheck`로 돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
|
||||
문서를 낡게 만든다.
|
||||
|
||||
| 검사 | 보는 것 |
|
||||
|
||||
+10
-10
@@ -50,21 +50,21 @@
|
||||
|
||||
## 3. 경로 → 전문가
|
||||
|
||||
리드가 바뀐 경로로 렌즈를 고르는 표다. 지식 스킬의 `paths`와 맞춘다. `reviewer` 하나에는 렌즈 1~3개를 준다. 관점이 서로 다르고 볼 파일이 많으면 `reviewer`를 렌즈별로 나눠 띄운다.
|
||||
리드가 바뀐 경로로 렌즈를 고르는 표다. 1열은 1차 렌즈 스킬의 `paths`를 그대로 옮긴 것이다(`scripts/tests/test_claude_setup.py`가 대조한다. 스킬의 `paths`를 바꾸면 이 표도 바꾼다). `reviewer` 하나에는 렌즈 1~3개를 준다. 관점이 서로 다르고 볼 파일이 많으면 `reviewer`를 렌즈별로 나눠 띄운다.
|
||||
|
||||
| 경로(glob) | 1차 렌즈 | 이럴 때 더한다 |
|
||||
|---|---|---|
|
||||
| `src/domain/core/**`, `src/application/*/**`, `src/shared-contract/**` | be-domain(판정은 `arch-reviewer`) | 오류 코드가 바뀜 → be-api-contract, 포트 계약이 바뀜 → be-testing |
|
||||
| `src/adapter/outbound/persistence-*/**`, `**/db/migration/**` | be-persistence | 새 조회·인덱스 → be-performance, outbox·멱등성 행 → be-messaging, 응답·이벤트 필드로 드러남 → be-api-contract |
|
||||
| `src/adapter/*/messaging*/**`, `src/bootstrap/{outbox-relay,idempotency,durable-operation}/**`, `**/outbox/**`, `**/idempotency/**`, `**/contracts/messaging/**` | be-messaging | 테이블·잠금 → be-persistence, schema version → be-api-contract, handler 권한 표시 → be-security |
|
||||
| `src/adapter/outbound/persistence-*/**`, `**/db/migration/**`, `docs/jpa/**`, `docs/mongodb/**` | be-persistence | 새 조회·인덱스 → be-performance, outbox·멱등성 행 → be-messaging, 응답·이벤트 필드로 드러남 → be-api-contract |
|
||||
| `src/adapter/*/messaging*/**`, `src/bootstrap/{outbox-relay,idempotency,durable-operation}/**`, `**/outbox/**`, `**/idempotency/**`, `**/contracts/messaging/**`, `src/application/core/src/main/java/dev/caskeleton/application/messaging/**` | be-messaging | 테이블·잠금 → be-persistence, schema version → be-api-contract, handler 권한 표시 → be-security |
|
||||
| `src/adapter/inbound/**` | be-api-contract + be-security | 새 조회·목록 → be-performance, 로그·헤더 → be-observability |
|
||||
| `src/bootstrap/app/**`, `**/security/**`, `**/authz/**`, `docs/registries/secrets-classification.yaml`, `docs/security/**` | be-security | env 키·공개 경로 → be-api-contract, `runtimeOnly` 줄·lockfile → be-build-ci |
|
||||
| `docs/registries/{metrics,mdc-keys}.yaml`, `docs/observability/**`, `**/observability/**`, `**/observation/**`, `**/tracing/**`, `src/bootstrap/service-runtime/**` | be-observability | 로그·지표에 실리는 값 → be-security |
|
||||
| `docs/registries/{error-codes,env-keys,headers}.yaml`, `docs/architecture/*-api-surface.txt`, `docs/web/**`, `**/*.graphqls` | be-api-contract | 공개 경로·헤더 → be-security, 계약 시험 → be-testing |
|
||||
| `src/adapter/outbound/**`(위 둘 밖: httpclient, cache-redis, notification, fileserver 등), `**/*Performance*`, `**/jmh/**` | be-performance | 외부 호출 대상·자격 증명 → be-security, 결과 불명 → be-messaging |
|
||||
| `build-logic/**`, `**/build.gradle`, `**/gradle.lockfile`, `gradle/**`, `config/**`, `.gitea/**`, `.github/**`, `scripts/**` | be-build-ci | 새 의존성·버전 → be-security, lane 안 테스트 → be-testing |
|
||||
| `**/src/test/**`, `**/src/testFixtures/**`, `**/src/*Test/**` | be-testing | 계약이 약속하는 동작 → 그 분야 렌즈 |
|
||||
| `docs/**/*.md`, `**/AGENTS.md`, `**/README.md`, `.claude/**/*.md` | be-docs | 문서가 설명하는 동작 → 그 분야 렌즈 |
|
||||
| `src/bootstrap/app/**`, `**/security/**`, `**/authz/**`, `**/authorization/**`, `docs/registries/secrets-classification.yaml`, `docs/security/**`, `.env.example`, `.trivyignore.yaml`, `.github/dependency-vulnerability-policy.md` | be-security | env 키·공개 경로 → be-api-contract, `runtimeOnly` 줄·lockfile → be-build-ci |
|
||||
| `docs/registries/{metrics,mdc-keys}.yaml`, `docs/observability/**`, `docs/runbooks/**`, `**/observability/**`, `**/observation/**`, `**/tracing/**`, `**/*Metrics*`, `**/logback-spring.xml`, `src/bootstrap/service-runtime/**` | be-observability | 로그·지표에 실리는 값 → be-security |
|
||||
| `docs/registries/{error-codes,env-keys,headers}.yaml`, `docs/architecture/*-api-surface.txt`, `docs/web/**`, `docs/security/public-paths-snapshot.txt`, `docs/upgrade/**`, `.env.example`, `**/*.graphqls`, `**/contracts/messaging/**`, `**/released-payload-schemas.sha256` | be-api-contract | 공개 경로·헤더 → be-security, 계약 시험 → be-testing |
|
||||
| `src/adapter/outbound/**`(위 둘 밖: httpclient, cache-redis, notification, fileserver 등), `**/*Performance*`, `**/*PerformanceTest/**`, `**/jmh/**`, `docs/httpclient/performance-baseline.md`, `docs/web/virtual-thread-profile.md` | be-performance | 외부 호출 대상·자격 증명 → be-security, 결과 불명 → be-messaging |
|
||||
| `build-logic/**`, `**/build.gradle`, `settings.gradle`, `gradle/**`, `gradle.properties`, `**/gradle.lockfile`, `**/settings-gradle.lockfile`, `config/**`, `Dockerfile`, `.gitea/**`, `.github/**`, `scripts/**`, `renovate.json` | be-build-ci | 새 의존성·버전 → be-security, lane 안 테스트 → be-testing |
|
||||
| `**/src/test/**`, `**/src/testFixtures/**`, `**/src/*Test/**`, `**/src/*Testkit/**`, `docs/testing/**`, `gradle/container-images.properties` | be-testing | 계약이 약속하는 동작 → 그 분야 렌즈 |
|
||||
| `docs/**/*.md`, `**/AGENTS.md`, `**/README.md`, `**/CLAUDE.md`, `.claude/**/*.md` | be-docs | 문서가 설명하는 동작 → 그 분야 렌즈 |
|
||||
|
||||
## 4. 넘김 지도
|
||||
|
||||
|
||||
@@ -54,7 +54,7 @@ mkdir -p ~/<작업 이름>-logs
|
||||
uptime # 다른 빌드가 돌고 있는지 부하를 본다
|
||||
|
||||
# 3) 공유 잠금 아래에서 한 번에 하나씩 돌리고 rc와 로그를 남긴다
|
||||
cd ~/workspace/<작업 이름>/src
|
||||
cd ~/workspace/<작업 이름>
|
||||
flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --no-daemon --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"
|
||||
|
||||
# 4) 끝나면 worktree를 지운다
|
||||
@@ -84,7 +84,7 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업
|
||||
- 형식은 편집 훅이 파일마다 맞추므로 보통 바뀌는 것이 없다. 그래도 커밋을 나누기 전에 확인한다(나눈 뒤에 고치면 앞 커밋을 다시 만들어야 한다). 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다.
|
||||
|
||||
```bash
|
||||
ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --no-daemon --console=plain'
|
||||
ssh desktop 'cd ~/workspace/<작업 이름> && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --no-daemon --console=plain'
|
||||
ssh desktop 'cd ~/workspace/<작업 이름> && git diff --binary' | git apply --index && git write-tree # 노트북
|
||||
ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' # 같은 해시여야 한다
|
||||
```
|
||||
|
||||
@@ -61,7 +61,7 @@
|
||||
| 학습 문서(지난 것) | 삭제된 코드를 설명하는 학습 문서(지금 `docs/history/study/*.ko.md`, `docs/history/packages/*-superpowers-package/`)는 현재 코드에 맞게 갱신 → 2026-11-07 갱신하지 않고 기록으로 보관(머리 블록만 단다)으로 바뀜 | 소유자 | 2026-09-25 | 결정 6, design-docs `repo-structure/README.md` 3.2절 |
|
||||
| 문서 체계 | 문서를 수명으로 나눈다. 살아 있는 문서는 제자리에 두고 한국어로 옮긴다. 기록은 `docs/history/`, 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`에 둔다. 폴더 이름은 짝 프론트와 같이 쓴다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, 적용은 `docs/README.md` |
|
||||
| 한국어의 범위 | 살아 있는 문서는 본문까지 한국어로 쓴다. 기록 문서는 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달고 본문은 원문 그대로 둔다. 상태는 한국어 고정 어휘다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
|
||||
| 문서 검사 | 언어·머리 블록·참조·숫자 검사를 PR에서 실패로 둔다(`scripts/check-docs.py`, workflow `docs-check`) | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, `docs/README.md` 「문서 검사」 |
|
||||
| 문서 검사 | 언어·머리 블록·참조·숫자 검사를 PR에서 실패로 둔다(`scripts/check-docs.py`, workflow `docs-check`) → 2026-11-08 workflow를 셋으로 접으며 `pr.yml` `done`의 `:prCheck` 안 `documentCheck`로 옮겼다(아래 2.7 「workflow 단계 job 모양」) | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, `docs/README.md` 「문서 검사」 |
|
||||
| 학습 문서 | `docs/history/study/`에 기록으로 보관한다. 코드에 맞춰 갱신하지 않고 머리 블록만 단다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
|
||||
| 문서 규칙 정본 | design-docs `conventions/docs-system.md`(두 템플릿 공통). 이 repo의 적용은 `docs/README.md`에 적는다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
|
||||
| 레지스트리 yaml 설명 칸 | 번역한다. 그 칸을 읽는 테스트를 먼저 찾는다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
|
||||
@@ -190,13 +190,15 @@
|
||||
| 의존성 checksum | 추가 안 함(보류) | 소유자 | 결정 19 |
|
||||
| 취약점이 있는 의존성 버전 | 고친 버전으로 올리는 것이 먼저다. 고친 버전 중 가장 작은 것을 고르고, 짝으로 움직이는 라이브러리(httpclient5와 httpcore5, gRPC와 protobuf)는 upstream이 선언한 짝을 따른다. Boot BOM이 관리하면 Boot 패치를 먼저 보고, 없으면 BOM 속성 override(build-logic `JavaConventionsPlugin`, 이유와 지울 조건 옆). 어떤 leaf도 선언하지 않는데 upstream이 낡은 버전을 가져오면 카탈로그 `pinned-*`로 모든 구성에 고정한다. 무시 목록(`.trivyignore.yaml`)은 고친 버전이 없을 때만, 묻고 쓴다 | 기본값(2026-11-07) | `gradle/libs.versions.toml` 「Pinned」, 업그레이드 안내 `docs/upgrade/2026-11-maturity-review.md` B-54 |
|
||||
| Querydsl 취약 좌표 | `com.querydsl:querydsl-jpa`(CVE-2024-49203, 고친 버전 없음)를 템플릿이 싣지 않는다. persistence-jpa는 쓰는 타입(`Predicate`)이 있는 querydsl-core로만 컴파일하고, querydsl-jpa는 capability를 켜는 서비스가 더한다. leaf README는 그 좌표에 고친 버전이 없다고 적고 OpenFeign 포크(`io.github.openfeign.querydsl`)를 검토하라고 한다 | 위임(2026-11-07, 총괄이 권한 안 A를 확인) | 커밋 「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」, `src/adapter/outbound/persistence-jpa/README.md` 「라이브러리 API」 |
|
||||
| build-logic 의존성 잠금 | 잠그지 않음 + 문서화(보류) | 소유자 | 결정 27 |
|
||||
| 릴리스 이미지 서명 | cosign keyless, tag 릴리스에서 서명·검증 | 소유자 | 결정 31 |
|
||||
| build-logic 의존성 잠금 | ~~잠그지 않음 + 문서화(보류)~~ → 지금은 잠근다(`build-logic/build.gradle` `lockMode = LockMode.STRICT`, 2026-09-25 커밋부터). 바꾼 결정의 기록은 없다 | 소유자 | 결정 27 |
|
||||
| 릴리스 이미지 서명 | ~~cosign keyless~~, tag 릴리스에서 서명·검증 → 2026-11-07 키 쌍으로 바꿈(아래 「릴리스 이미지 서명 키」) | 소유자 | 결정 31 |
|
||||
| 릴리스 이미지 서명 키 | cosign 키 쌍으로 서명한다. Gitea Actions는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다. 개인 키와 비밀번호는 repo secret이다 | 소유자(2026-11-07) | `docs/work/operate.md` 4.3절, `.gitea/workflows/release.yml` |
|
||||
| gRPC `.proto` | protobuf Gradle 플러그인 + Buf. 2026-11-08부터 `grpc-library` repo의 `ci` 단계 | 소유자 | 결정 18 |
|
||||
| SpotBugs 신뢰도 | MEDIUM으로 내림. 패턴 단위 제외는 이유를 단다 | 위임 | `1101` 15절(08-07) |
|
||||
| 테스트 코드 정적 분석 | `testQualityCheck`는 `mainCheck` | 위임 | `1103` 14절 |
|
||||
| lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) |
|
||||
| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② |
|
||||
| workflow 명령의 빌드 판정 | ~~같은 셸의 `cd <상대 경로>`도 따라간다~~ → 2026-11-08 셸을 해석하지 않게 바꿈(아래 「workflow 단계 job 모양」) | 소유자 | `1103` 15절 ② |
|
||||
| workflow 단계 job 모양 | workflow는 `pr.yml`·`main.yml`·`release.yml` 셋이다. 단계 job의 `run:`은 셸 문법 없는 `./gradlew` 한 줄이나 `bash scripts/<이름>.sh` 한 줄이고, `verifyStrictLaneStages`는 셸을 해석하지 않고 이 고정 형식만 본다 | 소유자(2026-11-08) | design-docs `repo-structure/03-ci.md` 7·11절, `build-logic/AGENTS.md`, `StrictLaneStagesPlugin` Javadoc |
|
||||
| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `build-logic/AGENTS.md` 「lane 캐시와 성능 lane」 |
|
||||
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」 |
|
||||
| MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) |
|
||||
|
||||
@@ -16,10 +16,10 @@
|
||||
## 2. 라이브러리를 고칠 때
|
||||
|
||||
- 템플릿 안에서 라이브러리 코드를 고치지 않는다. 라이브러리 repo에서 고치고 릴리스한다.
|
||||
- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 두 repo에 브랜치를 하나씩 만들고, 두 repo를 같은 부모 폴더에 둔다(desktop은 `~/workspace/`). 템플릿에서 명령 줄로만 라이브러리를 끼워 같이 시험한다(composite build: Gradle이 같은 `group:artifact`의 외부 의존성을 끼운 빌드의 프로젝트로 바꿔 끼운다). Gradle 루트가 `src/`라 경로는 두 단계 위다.
|
||||
- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 두 repo에 브랜치를 하나씩 만들고, 두 repo를 같은 부모 폴더에 둔다(desktop은 `~/workspace/`). 템플릿에서 명령 줄로만 라이브러리를 끼워 같이 시험한다(composite build: Gradle이 같은 `group:artifact`의 외부 의존성을 끼운 빌드의 프로젝트로 바꿔 끼운다). Gradle 루트가 저장소 루트라 경로는 한 단계 위다.
|
||||
|
||||
```bash
|
||||
./gradlew --include-build ../../messaging-library <태스크>
|
||||
./gradlew --include-build ../messaging-library <태스크>
|
||||
```
|
||||
|
||||
그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다. 끼운 빌드는 자기 카탈로그로 컴파일되므로 라이브러리 repo CI 결과와 다를 수 있다. 최종 판정은 배포한 좌표로 돈 템플릿 게이트다.
|
||||
|
||||
@@ -130,6 +130,11 @@ HISTORY_PATTERNS = [
|
||||
("finding number with its chosen option (03-11 (b))",
|
||||
re.compile(r"(?<![\w./:-])\d{2}-\d{2} \([a-e]\)", re.ASCII)),
|
||||
("review README section (review README §15)", re.compile(r"review README §", re.ASCII)),
|
||||
# The 2026-11 program ran in work streams W1~W6, and the red team named findings BE-OBS-A,
|
||||
# BE-CONFIG-001. "(W4 BE-OBS-A)" told only a reader of that week's notes where a rule came from.
|
||||
("program work stream (W4)", re.compile(r"(?<![\w-])W\d(?![\w-])", re.ASCII)),
|
||||
("red team finding (BE-OBS-A, BE-CONFIG-001)",
|
||||
re.compile(r"(?<![\w-])(?:BE|FE)-[A-Z]{2,}-(?:\d{3}|[A-Z])(?![\w-])", re.ASCII)),
|
||||
("commit sha", re.compile(r"\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b", re.ASCII)),
|
||||
]
|
||||
|
||||
|
||||
@@ -136,6 +136,16 @@ class CheckWorkDocsTest(unittest.TestCase):
|
||||
self.assertFailsWith(f"{path}:3")
|
||||
(self.repo.root / path).unlink()
|
||||
|
||||
def test_a_work_stream_or_red_team_id_in_a_playbook_fails(self) -> None:
|
||||
for line in ("- 자세는 rate-limiting.md다(W4 BE-OBS-A).", "- BE-CONFIG-001로 고쳤다.", "- W4에서 정했다."):
|
||||
with self.subTest(line=line):
|
||||
self.repo.write("docs/work/operate.md", f"# operate.md\n\n{PLAYBOOK}{line}\n")
|
||||
self.assertFailsWith("docs/work/operate.md:")
|
||||
|
||||
def test_words_that_only_look_like_a_work_stream_pass(self) -> None:
|
||||
self.repo.write("docs/work/operate.md", f"# operate.md\n\n{PLAYBOOK}- W3C 표준과 HTTP-W1-x는 이름이 아니다.\n")
|
||||
self.assertEqual(self.repo.run()[0], 0)
|
||||
|
||||
def test_local_claude_state_is_not_checked(self) -> None:
|
||||
self.repo.write(".claude/worktrees/other/AGENTS.md", "# 다른 worktree\n\n- 리뷰 05-18.\n")
|
||||
self.assertEqual(self.repo.run()[0], 0)
|
||||
|
||||
@@ -61,6 +61,29 @@ def skill_paths(path: Path) -> list[str]:
|
||||
return re.findall(r'-\s+"([^"]+)"', block.group(1)) if block else []
|
||||
|
||||
|
||||
def expand_braces(pattern: str) -> list[str]:
|
||||
"""`a/{b,c}/d` → [`a/b/d`, `a/c/d`]. One brace group is enough for the patterns in experts.md."""
|
||||
match = re.search(r"\{([^}]*)\}", pattern)
|
||||
if not match:
|
||||
return [pattern]
|
||||
return [pattern[:match.start()] + part + pattern[match.end():] for part in match.group(1).split(",")]
|
||||
|
||||
|
||||
def experts_lens_paths() -> dict[str, set[str]]:
|
||||
"""experts.md 3절 표: 1열의 glob을 2열(1차 렌즈)이 이름 대는 지식 스킬마다 모은다."""
|
||||
text = EXPERTS.read_text(encoding="utf-8")
|
||||
section = text.split("## 3. ", 1)[1].split("\n## ", 1)[0]
|
||||
lenses: dict[str, set[str]] = {}
|
||||
for line in section.splitlines():
|
||||
cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
|
||||
if len(cells) < 2 or not cells[0].startswith("`"):
|
||||
continue
|
||||
globs = [g for raw in re.findall(r"`([^`]+)`", cells[0]) for g in expand_braces(raw)]
|
||||
for lens in re.findall(r"\bbe-[a-z-]+[a-z]", cells[1]):
|
||||
lenses.setdefault(lens, set()).update(globs)
|
||||
return lenses
|
||||
|
||||
|
||||
def front_matter(path: Path) -> dict[str, str]:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
match = re.match(r"^---\n(.*?)\n---\n", text, re.S)
|
||||
@@ -117,9 +140,13 @@ class SubagentTest(unittest.TestCase):
|
||||
|
||||
def test_verify_api_runs_the_app_on_the_desktop_under_the_shared_lock(self) -> None:
|
||||
text = (AGENTS / "verify-api.md").read_text(encoding="utf-8")
|
||||
for fragment in ("docs/work/operate.md", "flock /tmp/claude-gates/heavy.lock", "scripts/bootstrap-local.sh",
|
||||
"stash@{0}", "down"):
|
||||
# verify.sh takes the shared lock and turns the Gradle daemon off; a bare flock around the bootstrap script
|
||||
# left a daemon behind on the desktop, and the cleanup it pointed at was in no manual.
|
||||
for fragment in ("docs/work/operate.md", "scripts/verify.sh app --on here", "scripts/bootstrap-local.sh",
|
||||
"stash@{0}", "down", "git worktree remove"):
|
||||
self.assertIn(fragment, text)
|
||||
self.assertNotIn("heavy.lock scripts/bootstrap-local.sh", text)
|
||||
self.assertNotIn("정리법", text)
|
||||
|
||||
|
||||
class SkillTest(unittest.TestCase):
|
||||
@@ -155,6 +182,24 @@ class SkillTest(unittest.TestCase):
|
||||
rx = glob_regex(pattern)
|
||||
self.assertTrue(any(rx.fullmatch(f) for f in files), f"{name}: {pattern} matches no tracked file")
|
||||
|
||||
def test_no_instruction_runs_gradle_from_the_old_src_root(self) -> None:
|
||||
# The Gradle root moved from src/ to the repository root (2026-11-11). An instruction that still says
|
||||
# "run it in src/" sends a session to a folder with no gradlew.
|
||||
stale = re.compile(r"명령은 `src/`에서|cd [^`'&;|]*?/src(?=[ `'&;]|$)", re.M)
|
||||
roots = [REPO / ".claude", REPO / "docs/work"]
|
||||
files = [REPO / "AGENTS.md", REPO / "CLAUDE.md"] + [f for root in roots for f in root.rglob("*.md")]
|
||||
hits = [f"{f.relative_to(REPO)}:{n}" for f in files if "worktrees" not in f.relative_to(REPO).parts
|
||||
for n, line in enumerate(f.read_text(encoding="utf-8").splitlines(), 1) if stale.search(line)]
|
||||
self.assertEqual(hits, [])
|
||||
|
||||
def test_the_experts_path_table_lists_exactly_each_skill_paths(self) -> None:
|
||||
# The lead picks lenses from this table; a glob the skill has but the table lacks is a lens never picked.
|
||||
table = experts_lens_paths()
|
||||
for name in self.KNOWLEDGE:
|
||||
with self.subTest(skill=name):
|
||||
self.assertEqual(table.get(name, set()), set(skill_paths(SKILLS / name / "SKILL.md")),
|
||||
"docs/work/experts.md 3절 1열 vs .claude/skills/<name>/SKILL.md paths")
|
||||
|
||||
def test_the_experts_manual_names_every_expert_and_the_rule_points_at_it(self) -> None:
|
||||
manual = EXPERTS.read_text(encoding="utf-8")
|
||||
for name in self.KNOWLEDGE + [path.stem for path in AGENTS.glob("*.md")]:
|
||||
|
||||
Reference in New Issue
Block a user