From 6ff75b76bd0231aef14d95b4f3073cc1b389bc2c Mon Sep 17 00:00:00 2001 From: Duchan Date: Sat, 15 Aug 2026 00:22:41 +0900 Subject: [PATCH 1/3] docs(ios-agent): drop the review-record link a contributor cannot open MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `.work/` is gitignored, so `.work/reviews/fix__touch-helper-death-recovery.md` resolves for nobody but the author. The sentence it hung off already carries the reasoning — the conditional ownership record was removed as untestable and put back once a review found the case — so the pointer added a dead end, not depth. Co-Authored-By: Claude Opus 5 (1M context) --- packages/ios-agent/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/ios-agent/AGENTS.md b/packages/ios-agent/AGENTS.md index 8bd4e976..97d2cc6f 100644 --- a/packages/ios-agent/AGENTS.md +++ b/packages/ios-agent/AGENTS.md @@ -193,7 +193,7 @@ Five things about it are easy to undo by accident: readiness exists: during the start-up window the open is refused while the process is alive and about to become ready, so identity would then pass and the continuation would reach a process that never saw the down. This was removed once as untestable and put back after a review found - the case; see `.work/reviews/fix__touch-helper-death-recovery.md`. + the case. - **Replacing is bounded by a rolling window** — at most 3 spawns in any 30s. Deliberately not a count of consecutive fast failures: the helper's start-up is expensive, so "died too fast" cannot be separated from "died slowly" without guessing how long start-up takes, and a helper that From 2e1c6b910bb1bf0a22fd34ef3346c46d3f3168b3 Mon Sep 17 00:00:00 2001 From: Duchan Date: Sat, 15 Aug 2026 00:26:01 +0900 Subject: [PATCH 2/3] docs: track the .work conventions file, and give reviews/ a lifecycle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `AGENTS.md:86` and `INDEX.md:35` both link `.work/CLAUDE.md`, which `.gitignore` excluded along with the logs it documents — so the link resolved for the author and 404'd for everyone else. Track the conventions file; the logs stay private. It gains the rule its own archive section was missing: a review record lives as long as its branch. Without it, 59 of the 61 records in `reviews/` were for branches already merged or deleted. The cost is not disk, it is what the next session reads when it scans that directory. And it now says not to link the directory from committed docs, which is the defect the previous commit removed. Co-Authored-By: Claude Opus 5 (1M context) --- .gitignore | 6 ++-- .work/CLAUDE.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 .work/CLAUDE.md diff --git a/.gitignore b/.gitignore index c8b0455f..31ad93cb 100644 --- a/.gitignore +++ b/.gitignore @@ -10,8 +10,10 @@ out/ # dashboard build bundled into relay packages/relay/public/ -# local work logs (not for contributors) -.work/ +# local work logs (not for contributors) — the conventions file is committed, +# because AGENTS.md and INDEX.md link to it and the logs themselves stay private +.work/* +!.work/CLAUDE.md # env .env diff --git a/.work/CLAUDE.md b/.work/CLAUDE.md new file mode 100644 index 00000000..d96f60a9 --- /dev/null +++ b/.work/CLAUDE.md @@ -0,0 +1,96 @@ +# .work — CLAUDE.md + +로컬 전용 작업 로그 디렉토리. 로그는 git에 커밋되지 않고, 규약인 이 파일만 추적된다 — 루트 +`AGENTS.md`와 `INDEX.md`가 여기를 링크하기 때문이다. + +--- + +## 파일 명명 규칙 + +``` +YYYY-MM-DD-{topic}-{type}.md +``` + +예시: `2026-05-08-agent-core-interface-plan.md` + +--- + +## 메타데이터 (frontmatter) + +모든 파일 상단에 아래 형식을 포함한다. + +```yaml +--- +created: YYYY-MM-DD +status: draft | in-progress | done | blocked +type: plan | review | compound | todo +phase: 1 | 2 | 3 | 4 | 5 | 5+ +topic: 한 줄 요약 +--- +``` + +| 필드 | 설명 | +|------|------| +| `created` | 파일 생성일 | +| `status` | 현재 진행 상태 | +| `type` | 워크플로우 단계 (plan / review / compound / todo) | +| `phase` | tapflow 로드맵 Phase (1–5+). 해당 없으면 생략 | +| `topic` | 작업 주제 한 줄 요약 | + +--- + +## type별 용도 + +- **plan** — 요구사항 + 테스트 케이스 정의. 작업 시작 전 작성. +- **review** — 엣지 케이스 검토 + 실제 데이터 검증 결과. +- **compound** — 재사용할 테스트·코드·프롬프트 템플릿 묶음. +- **todo** — 스코프 밖으로 분리된 항목 모음. 작업 시작 시 plan으로 전환한다. + +--- + +## 프로그램 단위 계획 — 날짜 규칙의 예외 + +여러 PR에 걸치는 작업은 **날짜 접두사 없는 대문자 파일 하나**로 두고 갱신한다 — 현재 +`WIRE-CONTRACT-PLAN.md`. + +PR 단위로 쪼개면 리뷰 안전성은 확보되지만 **전체 그림을 놓치고 미시적 문제에 매몰된다.** +2026-08-08에 그게 일어났다: 입력 경로 6건을 하루에 고치면서 설계 계획이 **세 번 폐기됐고, 세 폐기가 +같은 모양**이었는데(구조 문제에 국소 패치) 두 번째에서 알아채지 못했다. 컨텍스트는 리셋되고, PR +계획은 PR 단위, 리뷰 기록은 브랜치 단위여서 **프로그램 단위인 것이 없었다.** + +그 파일이 반드시 담아야 하는 것: + +- **현재 상태** — 층/단계별 진행, 맨 위에. 먼저 읽는 것 +- **다음 행동** — 하나 +- **결정 로그** — 제안됐다가 폐기된 것과 그 근거. 컨텍스트가 리셋되면 같은 걸 또 제안하므로 이게 + 핵심이다. 틀린 것으로 판명된 전제도 같이 남긴다 +- **이슈 매핑** — 새 이슈를 만드는 대신 기존 이슈를 층에 붙인다 + +층이 랜딩하면 **영구적 설계 근거는 해당 AGENTS.md로 옮긴다.** 이 파일은 진행 상태와 결정을 들고, +근거는 코드 옆에 산다. + +## 아카이브 + +`status: done`이 된 파일은 `archive/` 서브디렉토리로 이동한다. +`.work/`에는 진행 중(`draft` · `in-progress` · `blocked`) 파일만 유지한다. + +--- + +## reviews/ — adversarial review 기록 + +`reviews/<브랜치명>.md` (슬래시는 `__`로 치환). PR 생성 전 독립 컨텍스트 리뷰의 발견사항과 처리 내역(수정 / 스킵+사유)을 기록하고, 리뷰한 HEAD 커밋 해시를 포함한다. `.claude/hooks/adversarial-review-gate.sh`가 `gh pr create` 시 이 기록과 HEAD 일치를 강제한다. 절차 정의: 루트 AGENTS.md "Adversarial Review". + +**수명은 브랜치와 같다.** 브랜치가 머지되면 기록도 `reviews/archive/`로 옮긴다. 위 아카이브 규칙에 +`reviews/`가 빠져 있어서 2026-08-15 기준 61건 중 59건이 이미 머지됐거나 사라진 브랜치의 것이었다. +비용은 디스크가 아니라 다음 세션이 이 디렉터리를 훑을 때의 신호 대 잡음이다. + +**커밋되는 문서에서 이 디렉터리를 링크하지 않는다.** `.work/`는 gitignore라 기여자에게는 없는 +경로이고, 링크는 그쪽에서 끊긴 채로만 보인다. 같은 날 기준 61건 중 레포 안에서 인용된 유일한 1건이 +`packages/ios-agent/AGENTS.md`의 그런 링크였다. 남길 가치가 있는 근거는 링크가 아니라 승격으로 +옮긴다 — 코드 옆 주석, 패키지 AGENTS.md, `contributing/`. + +--- + +## 시작 방법 + +`/work-plan {topic}` 커맨드로 plan 문서를 생성한다. From f1a0723f8db68ee4b7ea7568a7948086eea53400 Mon Sep 17 00:00:00 2001 From: Duchan Date: Sat, 15 Aug 2026 00:49:54 +0900 Subject: [PATCH 3/3] docs: say which directory the active-files-only rule applies to The rule read `.work/` holds only in-progress files, one line under a sentence sending done files to `archive/`. A human resolves that from the sentence above it; an agent following the rule literally has two instructions that conflict. Adding `reviews/archive/` gave it a second way to be read wrong, so name the level: the top of `.work/`, not what sits below it. Found by CodeRabbit on #556. Co-Authored-By: Claude Opus 5 (1M context) --- .work/CLAUDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.work/CLAUDE.md b/.work/CLAUDE.md index d96f60a9..a2db85f1 100644 --- a/.work/CLAUDE.md +++ b/.work/CLAUDE.md @@ -72,7 +72,8 @@ PR 단위로 쪼개면 리뷰 안전성은 확보되지만 **전체 그림을 ## 아카이브 `status: done`이 된 파일은 `archive/` 서브디렉토리로 이동한다. -`.work/`에는 진행 중(`draft` · `in-progress` · `blocked`) 파일만 유지한다. +`.work/` 최상위에는 진행 중(`draft` · `in-progress` · `blocked`) 파일만 유지한다. `archive/`와 +`reviews/`는 그 아래에 있으므로 이 규칙의 대상이 아니다. ---