docs(src): 계층 폴더마다 지역 규칙 AGENTS.md를 두고 CLAUDE.md가 가져온다

계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.

src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).

- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
  본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
  아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
  양식을 가리킨다.

버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).

위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).

검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
This commit is contained in:
DongHyeonka
2026-11-08 22:57:03 +09:00
parent 93e3c7b1a6
commit f117a5af41
29 changed files with 248 additions and 30 deletions
+3 -8
View File
@@ -7,12 +7,7 @@ paths:
# adapter와 import 규칙을 고칠 때
정본은 `.dependency-cruiser.json`(규칙), `docs/architecture/layers.md`(설명), `docs/work/reference/structure.md`(바꿀 때 같이 고칠 것)다. 판정은 `check:architecture`(FE-GATE-010)다.
규칙의 정본은 `src/adapters/AGENTS.md`(그 폴더의 지역 규칙)와 `.dependency-cruiser.json`이다. 이 파일은 다시 쓰지 않고 가리킨다.
- 그룹 밖에서는 그 그룹의 `index.ts`(배럴)로만 들어간다. 배럴 밖으로 공개 표면을 늘리지 않는다. 2단계 `index.ts`는 공개 배럴이 아니다(예외: `storage/indexeddb`, `storage/opfs`).
- adapter끼리 import하는 예외는 kernel 셋뿐이다: `src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`. 새 공유 프리미티브는 `src/adapters/platform/`에 넣는다. 새 파일 단위 예외를 만들거나 제안하지 않는다.
- adapter는 presentation·bootstrap을 import하지 않는다. 관측 vendor SDK는 adapter 뒤에만 둔다.
- adapter 파일을 더하거나 옮기거나 지우면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(`check:adapter-inventory`).
- 규칙을 더하거나 이름을 바꾸면 `docs/architecture/layers.md` 규칙 표도 고친다. 예외는 `pathNot`과 `comment`(이유·담당·재검토 조건)를 함께 쓴다. 규칙·예외 변경은 크기가 큼이다(`docs/work/README.md` 2절).
- 편집 훅(N3)은 편집한 파일의 import를 이 규칙 파일에 대 보고 의심 줄을 알린다. 그래프 전체(사이클)는 게이트만 본다.
- 실패 분류는 status와 code를 함께 보고, 짝 백엔드 쓰기 응답 판정은 `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE` 하나만 쓴다. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다.
- import 규칙을 더하거나 이름을 바꾸면 `docs/architecture/layers.md` 규칙 표도 고친다. 예외는 `pathNot`과 `comment`(이유·담당·재검토 조건)를 함께 쓴다. 규칙·예외 변경은 크기가 큼이다(`docs/work/README.md` 2절).
- 편집 훅(N3)은 편집한 파일의 import를 규칙 파일에 대 보고 의심 줄을 알린다. 그래프 전체(사이클)는 `check:architecture`만 본다.
+1 -8
View File
@@ -7,11 +7,4 @@ paths:
# 기능 폴더를 고칠 때
정본은 `docs/manual/`(만드는 순서와 판단 기준)과 `docs/work/new-feature.md`(크기·완료 기준)다. 새 기능은 스킬 `new-feature`로 시작한다.
- 뼈대는 `corepack pnpm create:feature <id>`로 만든다. 다른 기능 폴더를 복사해 이름을 바꾸지 않는다.
- 기능끼리, context끼리 import하지 않는다. 기능의 계층(domain → application → adapters·presentation)은 `.dependency-cruiser.json`의 `feature-*` 규칙을 따른다. 기능 밖 adapter는 기능의 `adapters/`나 `src/features/feature-adapter-contribution.ts`로만 닿는다.
- 기능 폴더 밖 파일을 생성 명령 밖에서 고쳐야 하면 거기서 멈춘다(`docs/manual/03-outside-feature-folder.md`). 크기가 큼이다.
- 기능 테스트는 `tests/features/<id>/`에 둔다. 기능과 함께 지워진다.
- 기능을 더하거나 지우면 초기 JS 기록과 기능 모양 기록이 바뀐다. 생성 명령 출력 `Next:`의 명령으로 다시 쓴다. 예산을 넘으면 올리기 전에 멈추고 묻는다.
- 결과 불명 쓰기와 재전송은 `docs/manual/02-decision-tables.md` 3·4절 기준이다.
규칙의 정본은 `src/features/AGENTS.md`·`src/contexts/AGENTS.md`(지역 규칙), 절차는 `docs/work/new-feature.md`와 `docs/manual/`이다. 새 기능은 스킬 `new-feature`로 시작한다. 이 파일은 다시 쓰지 않고 가리킨다.
+2 -2
View File
@@ -1,6 +1,6 @@
# AGENTS.md — 프론트 템플릿의 정본
도메인 로직을 뺀 공통 기능을 갖춘 React + Vite 프론트 출발점이다(`PRODUCT.md`). 브라우저 SPA + 정적 호스팅 + Service Worker이고 SSR은 없다. 서비스는 복사해 기능 폴더를 채운다. 개발 compose는 짝 백엔드의 `compose.yaml`을 쓴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이고, 갈라진 중복 복사본은 결함이다.
도메인 로직을 뺀 공통 기능을 갖춘 React + Vite 프론트 출발점이다(`PRODUCT.md`). 브라우저 SPA + 정적 호스팅 + Service Worker이고 SSR은 없다. 서비스는 복사해 기능 폴더를 채운다. 방향과 문제 정의는 `docs/vision.md`·`docs/problem-statement.md`(소유자가 채우는 빈 양식)다. 개발 compose는 짝 백엔드의 `compose.yaml`을 쓴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이고, 갈라진 중복 복사본은 결함이다.
## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다
@@ -16,7 +16,7 @@
- 새 기능은 `corepack pnpm create:feature <id>`로 만들고 `docs/manual/` 순서로 채운다.
- 게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다(설명 `docs/operations/ci-quality-gates.md`).
- adapter 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다.
- 폴더를 가로지르는 규칙(테스트·문서·설정)은 `.claude/rules/`, 문서 위치 규칙은 `docs/README.md`다.
- 지역 규칙은 작업 파일과 가장 가까운 `src/<계층>/AGENTS.md`다. 폴더를 가로지르는 규칙(테스트·문서·게이트 기준)은 `.claude/rules/`, 문서 위치 규칙은 `docs/README.md`다.
## 맡은 일
+2
View File
@@ -149,6 +149,8 @@
| 139 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/http/fileserver-upload.ts` | [Network/state](./01-network-and-state.md) |
| 142 | `src/adapters/AGENTS.md` | 계층 규칙 문서(코드 아님, 리뷰 대상 아님) |
| 143 | `src/adapters/CLAUDE.md` | 위 문서를 가져오는 한 줄(`@AGENTS.md`) |
합계: **141/141**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
+3 -3
View File
@@ -29,7 +29,7 @@
1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다.
2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 「결정이 필요한 것」「조치」「미검증」 절. 정한 것은 다시 묻지 않는다.
3. 바뀌는 경계를 찾는다. 위험은 파일 수가 아니라 경계로 정한다: 사용자 데이터(결과 불명 쓰기, 브라우저 저장소), 공개 포트·배럴, merge 게이트, 짝 백엔드 계약을 건드리면 높다.
3. 바뀌는 경계를 찾고 가장 가까운 `src/<계층>/AGENTS.md`를 읽는다. 위험은 파일 수가 아니라 경계로 정한다: 사용자 데이터(결과 불명 쓰기, 브라우저 저장소), 공개 포트·배럴, merge 게이트, 짝 백엔드 계약을 건드리면 높다.
4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은 `.claude/skills/`다(`new-feature`, `desktop-gates`). 파일을 바꾸는 일은 직접 하거나 하위 세션에 맡기고, 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절).
5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
6. 무거운 실행(pnpm, 게이트, 브라우저, 빌드)은 [operate.md](operate.md) 「실행 위치」대로 `scripts/verify.sh`로 한다.
@@ -70,6 +70,6 @@
## 8. 이 폴더를 고칠 때
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 15줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
- 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 루트 `AGENTS.md`·`CLAUDE.md`, `.claude/` 아래 문서도 같다. `reference/decisions.md`·`reference/defect-patterns.md`와 리뷰 문서는 ID를 둔다.
- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 15줄, 폴더 지역 규칙(`src/**/AGENTS.md`, 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`) 200줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다.
- 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서도 같다. `reference/decisions.md`·`reference/defect-patterns.md`와 리뷰 문서는 ID를 둔다.
- 고친 뒤 `scripts/verify.sh docs`(노트북)와 desktop `scripts/verify.sh script verify:documentation`이 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다.
+38 -6
View File
@@ -10,16 +10,18 @@ things break that, and both are mechanical:
1. History IDs in the body. A sentence such as "fixed as in 1103/11-07" means nothing to a reader
who does not know that review. History belongs in `docs/work/evidence.md` and the two reference
files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). The
same rule covers the other files a new session reads first: the root `AGENTS.md` and `CLAUDE.md`
and the documents under `.claude/` (rules, skills, subagents). Review documents keep their IDs.
same rule covers the other files a new session reads first: the root `AGENTS.md` and `CLAUDE.md`,
every folder rule book `src/**/AGENTS.md` and the documents under `.claude/` (rules, skills,
subagents). Review documents keep their IDs.
2. Length. Each entry file has a line limit and the entry path (map + root `CLAUDE.md` + README +
one playbook) has a total limit, so a session reads the whole path instead of skimming it. The
map limit is 40 lines (owner decision 2026-11-07: the root holds the rules, the map and the
router only).
It also checks that every playbook keeps the shared nine-section skeleton, that the "common
mistakes" section stays short, that `CLAUDE.md` starts with the import, and that relative links in
the checked files resolve. The same layout and limits as the paired backend template's checker.
mistakes" section stays short, that `CLAUDE.md` starts with the import, that every folder rule book
`src/**/AGENTS.md` has a `CLAUDE.md` beside it that only imports it (so Claude Code reads the same
book) and stays under 200 lines, and that relative links in the checked files resolve. The same layout and limits as the paired backend template's checker.
Standard library only, so it runs on the laptop and in the edit hook (scripts/hooks/hooks.py, N2).
`verify:documentation` (FE-GATE-017) checks the paths, scripts and gate IDs these documents name.
@@ -71,6 +73,9 @@ README_LIMIT = 80
PLAYBOOK_LIMIT = 150
ENTRY_PATH_LIMIT = 350
MISTAKES_LIMIT = 10
# A folder rule book is read whole whenever a file in that folder is opened (Claude Code: under 200).
MODULE_GUIDE_LIMIT = 200
SKIPPED_PARTS = {"node_modules", ".generated", "dist"}
SKELETON = [
"1. 언제 쓰나",
@@ -196,6 +201,31 @@ def check_claude_entry(errors: list[str]) -> None:
errors.append(f"{rel(CLAUDE_ENTRY)}: the first line must be '{IMPORT_LINE}'")
def module_guides() -> list[Path]:
"""Every src/**/AGENTS.md, the local rule book of a layer folder."""
return sorted(path for path in (REPO_ROOT / "src").rglob("AGENTS.md")
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts))
def check_guides(errors: list[str], report: list[str]) -> None:
longest = 0
for guide in module_guides():
lines = line_count(guide)
longest = max(longest, lines)
if lines > MODULE_GUIDE_LIMIT:
errors.append(f"{rel(guide)}: {lines} lines, limit {MODULE_GUIDE_LIMIT}")
if not guide.with_name("CLAUDE.md").is_file():
errors.append(f"{rel(guide.with_name('CLAUDE.md'))}: missing; it must be the one line '{IMPORT_LINE}'")
for entry in sorted(path for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts)):
lines = [line.strip() for line in entry.read_text(encoding="utf-8").splitlines() if line.strip()]
if lines != [IMPORT_LINE]:
errors.append(f"{rel(entry)}: must be exactly '{IMPORT_LINE}'; the rules live in AGENTS.md beside it")
if not entry.with_name("AGENTS.md").is_file():
errors.append(f"{rel(entry)}: imports {rel(entry.with_name('AGENTS.md'))}, which does not exist")
report.append(f"src/**/AGENTS.md: {len(module_guides())} files, longest {longest}/{MODULE_GUIDE_LIMIT}")
def claude_documents() -> list[Path]:
"""The tracked Claude Code documents a session reads: path rules, skills, subagent definitions.
Only these folders: the rest of .claude/ is local state (worktrees, hook state, settings.local.json)."""
@@ -203,7 +233,7 @@ def claude_documents() -> list[Path]:
def history_checked_files() -> list[Path]:
files = [MAP, CLAUDE_ENTRY] + claude_documents()
files = [MAP, CLAUDE_ENTRY] + claude_documents() + module_guides()
for path in sorted(WORK.rglob("*.md")):
if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED:
files.append(path)
@@ -262,7 +292,8 @@ def check_history(errors: list[str], report: list[str]) -> None:
def check_links(errors: list[str], report: list[str]) -> None:
checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + claude_documents())
checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + claude_documents()
+ module_guides())
for path, number, target in broken:
errors.append(f"{rel(path)}:{number}: broken relative link '{target}'")
report.append(f"relative links checked: {checked}")
@@ -308,6 +339,7 @@ def main() -> int:
if check_exists(errors):
check_limits(errors, report)
check_claude_entry(errors)
check_guides(errors, report)
check_skeleton(errors)
check_history(errors, report)
check_links(errors, report)
+1 -1
View File
@@ -26,7 +26,7 @@ Bash 직후 ──> post-bash ──> desktop에서 pnpm·게이트를 돌
| N5 | Stop | 이 세션에서 desktop만 확인할 수 있는 파일(아래 밖의 모든 파일)을 고친 뒤 desktop 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 편집 전까지 한 번 |
- N5가 "desktop 실행"으로 치는 것: `ssh <desktop 호스트> …`로 pnpm·`ci:gate`·`verify.sh`·vitest·playwright·`node scripts/…`를 돌린 명령, 또는 `scripts/verify.sh`를 `docs`·`hooks` 밖 단계로(`--on here` 없이) 돌린 명령.
- N5가 세지 않는 파일(노트북에서 확인되는 것): `.claude/`, `scripts/hooks/`, `scripts/tests/`, `scripts/check-work-docs.py`, `docs/ledger/`, `CLAUDE.md`. 이것들은 `scripts/verify.sh docs`·`hooks`가 노트북에서 본다.
- N5가 세지 않는 파일(노트북에서 확인되는 것): `.claude/`, `scripts/hooks/`, `scripts/tests/`, `scripts/check-work-docs.py`, `docs/ledger/`, `CLAUDE.md`, `src/**/AGENTS.md`·`CLAUDE.md`. 이것들은 `scripts/verify.sh docs`·`hooks`가 노트북에서 본다.
- N5가 기억하는 것은 `.claude/hook-state/<session_id>.json`이다(git이 무시한다).
- 권한 쪽 차단: `.claude/settings.json`의 `permissions.deny`가 실제 `.env`·`.env.local`·`.env.*.local`·`.env.<mode>` 읽기·쓰기를 막는다. `.env.example`은 막지 않는다.
+2 -1
View File
@@ -71,7 +71,7 @@ DOC_TIMEOUT = 20
# --- N5: an edit that only the desktop can check, until a desktop run --------------------------------------
# Laptop-checkable on their own: the hooks and their tests, the work-manual checker, the ledger, Claude
# settings and CLAUDE.md. Everything else is checked by gates that need pnpm.
# settings, CLAUDE.md and the folder rule books under src/ (scripts/check-work-docs.py checks them). Everything else is checked by gates that need pnpm.
LAPTOP_ONLY = (
re.compile(r"^\.claude/"),
re.compile(r"^scripts/hooks/"),
@@ -79,6 +79,7 @@ LAPTOP_ONLY = (
re.compile(r"^scripts/check-work-docs\.py$"),
re.compile(r"^docs/ledger/"),
re.compile(r"^CLAUDE\.md$"),
re.compile(r"^src/(?:.+/)?(?:AGENTS|CLAUDE)\.md$"),
)
DESKTOP_HOST = re.compile(r"desktop")
DESKTOP_WORK = re.compile(r"\b(?:pnpm|ci:gate|verify\.sh|vitest|playwright)\b|\bnode\s+scripts/")
+13
View File
@@ -106,6 +106,19 @@ class BrokenCopyTest(unittest.TestCase):
self.append("docs/work/README.md", "\n[x](missing.md)\n")
self.assertIn("broken relative link 'missing.md'", self.run_checker().stderr)
def test_a_folder_rule_book_needs_its_import_beside_it_and_no_history(self) -> None:
guide = self.root / "src/adapters/AGENTS.md"
guide.parent.mkdir(parents=True)
guide.write_text("# AGENTS.md\n\n- 규칙\n", encoding="utf-8")
self.assertIn("src/adapters/CLAUDE.md: missing", self.run_checker().stderr)
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n", encoding="utf-8")
self.assertEqual(self.run_checker().returncode, 0)
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n- 둘째 규칙\n", encoding="utf-8")
self.assertIn("must be exactly '@AGENTS.md'", self.run_checker().stderr)
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n", encoding="utf-8")
guide.write_text("# AGENTS.md\n\n- 1105/12-04처럼 고친다\n", encoding="utf-8")
self.assertIn("src/adapters/AGENTS.md:3:", self.run_checker().stderr)
def test_a_missing_reference_fails(self) -> None:
(self.root / "docs/work/reference/testing.md").unlink()
self.assertIn("docs/work/reference/testing.md: missing", self.run_checker().stderr)
+22
View File
@@ -57,6 +57,28 @@ class RootInstructionsTest(unittest.TestCase):
self.assertNotIn("서브에이전트를 병렬로", text, path)
class LayerGuideTest(unittest.TestCase):
"""Every top-level src/ folder has its rule book, readable by any agent, and Claude Code imports it."""
def test_every_layer_folder_has_a_rule_book_and_the_import_beside_it(self) -> None:
folders = sorted(path for path in (REPO / "src").iterdir() if path.is_dir() and not path.name.startswith("."))
self.assertTrue(folders)
for folder in folders:
guide = folder / "AGENTS.md"
self.assertTrue(guide.is_file(), f"{folder.name}: no AGENTS.md")
self.assertTrue(guide.read_text(encoding="utf-8").startswith(f"# AGENTS.md — `src/{folder.name}`"))
self.assertEqual((folder / "CLAUDE.md").read_text(encoding="utf-8"), "@AGENTS.md\n", folder.name)
def test_path_rules_point_at_the_folder_books_instead_of_copying_them(self) -> None:
for rule, book in (("adapters", "src/adapters/AGENTS.md"), ("features", "src/features/AGENTS.md")):
self.assertIn(f"`{book}`", (CLAUDE / "rules" / f"{rule}.md").read_text(encoding="utf-8"))
def test_the_owner_forms_exist_and_the_map_points_at_them(self) -> None:
for form in ("docs/vision.md", "docs/problem-statement.md"):
self.assertIn("(채울 것", (REPO / form).read_text(encoding="utf-8"), form)
self.assertIn(f"`{form}`", (REPO / "AGENTS.md").read_text(encoding="utf-8"))
class SubagentTest(unittest.TestCase):
AGENTS = CLAUDE / "agents"
+2 -1
View File
@@ -245,7 +245,8 @@ class TurnEndNudgeTest(RepositoryTestCase):
def test_files_the_laptop_checks_do_not_need_the_desktop(self) -> None:
for path in (".claude/rules/x.md", "scripts/hooks/hooks.py", "scripts/tests/test_x.py", "CLAUDE.md",
"docs/ledger/estimates.jsonl", "scripts/check-work-docs.py"):
"docs/ledger/estimates.jsonl", "scripts/check-work-docs.py", "src/adapters/AGENTS.md",
"src/features/CLAUDE.md"):
self.repo.write(path, "x\n")
run_event("post-edit", self.repo.payload(path))
self.assertIsNone(self.stop())
+18
View File
@@ -0,0 +1,18 @@
# AGENTS.md — `src/adapters` (재사용 capability runtime)
application 포트를 구현하는 HTTP, 인증, 저장소, query cache, telemetry, worker 등이다. 그룹마다 `src/adapters/<그룹>/index.ts`(배럴)가 공개 경계다.
## 지킬 것
- 그룹 밖에서는 배럴로만 들어온다. 2단계 `index.ts`는 공개 배럴이 아니다(예외 `storage/indexeddb`, `storage/opfs`).
- 다른 adapter 그룹을 import하지 않는다(`adapters-do-not-know-other-concrete-adapters`). 예외는 kernel 셋(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이고 새 파일 단위 예외를 만들지 않는다. 새 공유 프리미티브는 `src/adapters/platform/`에 둔다.
- presentation·bootstrap을 import하지 않는다(`adapters-do-not-know-presentation`). 일반 worker는 네트워크·자격 증명 adapter를 모른다. Service Worker 입구는 페이지 코드가 아니다.
- 실패 분류는 status와 code를 함께 본다. 짝 백엔드 쓰기 응답 판정은 `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE` 하나다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:adapter-inventory`(FE-GATE-010 안): 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(이 파일도 거기 행이 있다)
- `check:browser-file-storage-boundaries`·`check:realtime-boundaries`(FE-GATE-010 안)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/integration`, `tests/contract`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+16
View File
@@ -0,0 +1,16 @@
# AGENTS.md — `src/application` (일반 유스케이스와 포트)
유스케이스, 포트, 정책, view-model이 있다. 구체 runtime을 모른다.
## 지킬 것
- presentation·adapters·bootstrap·React·TanStack을 import하지 않는다(`application-does-not-know-concrete-runtime`).
- 포트는 추가만 한다. 시그니처를 깨야 하면 결정을 받고 BREAKING으로 커밋한다.
- 결과 불명 쓰기의 재전송 판정은 한 곳에 둔다(`docs/manual/02-decision-tables.md` 3·4절).
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `test:unit`(FE-GATE-005)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`, 포트 소비자 계약은 `tests/contract`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+15
View File
@@ -0,0 +1,15 @@
# AGENTS.md — `src/apps` (배포 단위)
앱마다 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다.
## 지킬 것
- adapter를 직접 import하지 않는다(`feature-and-app-roots-do-not-reach-adapters`). 조립은 `src/bootstrap`이 한다.
- 선언은 작은 리터럴 머리다. `scripts/generate-product-feature-index.ts`가 읽어 `src/.generated/`를 만든다. 선언 모양을 바꾸면 그 생성기와 함께 고친다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:scale:pr`(FE-GATE-005 안): 앱·context 예산
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+17
View File
@@ -0,0 +1,17 @@
# AGENTS.md — `src/bootstrap` (조립 뿌리)
런타임 설정을 읽고, 구체 adapter를 만들어 application 포트에 끼우고, React를 붙이는 곳이다. 구체 adapter를 조립하는 곳은 여기 하나다.
## 지킬 것
- 업무 규칙을 두지 않는다. 판정·정책은 `src/application`·`src/platform`·기능 폴더에 둔다.
- 선택하지 않은 realtime·web-push runtime을 조립하지 않는다(`unselected-realtime-runtime-is-not-composed`). 기능 runtime은 `src/features/loaded-feature-runtimes.ts`만 불러온다(`boot-does-not-load-every-feature-runtime`).
- 제품마다 다른 조립은 제품 소유 파일 `src/bootstrap/product-composition.ts`에 둔다. 템플릿 소유 파일을 고쳐야 하면 결함이다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `build`(FE-GATE-011), `check:bundle`(FE-GATE-012): 초기 JS·파일 수 예산
- 런타임 설정 키를 바꾸면 루트 `README.md` 런타임 변수 표와 `verify:documentation`
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/integration`(조립된 경계), `tests/e2e`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+16
View File
@@ -0,0 +1,16 @@
# AGENTS.md — `src/contexts` (bounded context)
context마다 `context-module.ts`가 앱, 라우트 뿌리, 기능 예산을 선언한다. 생성 명령 `create:feature`가 새 context를 만든다.
## 지킬 것
- context끼리 import하지 않는다(`contexts-do-not-import-other-contexts`). adapter를 직접 import하지 않는다(`feature-and-app-roots-do-not-reach-adapters`).
- context 폴더를 손으로 만들거나 경계를 바꾸는 일은 크기가 큼이다(`docs/work/new-feature.md` 3절).
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:scale:pr`(FE-GATE-005 안): 기능 예산
- FE-GATE-020: 기능을 더하고 지운 사본
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+17
View File
@@ -0,0 +1,17 @@
# AGENTS.md — `src/contracts` (공유 어휘와 레지스트리)
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「Decision rule」이다.
## 지킬 것
- application·features·presentation·bootstrap을 import하지 않는다(`contracts-do-not-know-application`, `contracts-do-not-know-presentation-or-bootstrap`). zod는 여기의 `zod.ts`로만 들어간다.
- 레지스트리 행은 원본(스키마, descriptor)에서 뽑는다. 손으로 다시 적으면 대조 테스트를 같이 둔다.
- 제품마다 다른 계약은 제품 소유 파일 `src/contracts/product-contracts.ts`에 둔다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:registries`(FE-GATE-010 안), `test:runtime-schema`(FE-GATE-004)
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-007)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/runtime-schema`, `tests/unit`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+19
View File
@@ -0,0 +1,19 @@
# AGENTS.md — `src/features` (지울 수 있는 기능)
기능 하나는 `src/features/<id>/{domain,application,contracts,adapters,presentation}`이고 기능 폴더째 지울 수 있다. 이 폴더 바로 아래의 `*.ts`는 설치된 기능 목록(카탈로그)이다.
새 기능은 `corepack pnpm create:feature <id>`로 만들고 `docs/manual/` 순서로 채운다(스킬 `new-feature`).
## 지킬 것
- 기능끼리 import하지 않는다(`features-do-not-import-other-features`). 공용이 필요하면 `src/contracts/`나 kernel로 옮기는 일을 따로 묻는다.
- 기능 안 방향: domain은 framework·runtime을 모르고, application은 adapter·presentation을 모르고, presentation은 바깥 adapter를 모르고, adapters는 presentation을 모른다(`feature-*` 규칙 넷).
- 기능 밖 adapter는 기능의 `adapters/`나 `feature-adapter-contribution.ts`로만 닿는다(`feature-and-app-roots-do-not-reach-adapters`). presentation은 직접 fetch하지 않는다(`presentation-does-not-fetch-directly`).
- 기능 테스트는 `tests/features/<id>/`에 둔다. 플랫폼 테스트를 기능에 묶지 않는다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- FE-GATE-020: 생성한 기능을 더하고 지운 사본, 기능 제거는 `test:sample-removal -- --feature=<id>`
- 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)은 생성 출력 `Next:`의 명령으로 다시 쓴다
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/features/<id>/`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+15
View File
@@ -0,0 +1,15 @@
# AGENTS.md — `src/platform` (제품과 무관한 프리미티브)
예산, 실행 문맥, 회복력, telemetry 파이프라인, 오류 봉투, 릴리스 일관성처럼 어느 폴더든 쓰는 것이다. adapter kernel(`src/adapters/platform/`)과는 다른 폴더다.
## 지킬 것
- features·contexts·apps·adapters·bootstrap·presentation·application을 import하지 않는다(`platform-kernel-is-product-neutral`, 예외 `platform/routing/`).
- 확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다. 상수 `true` 판정을 두지 않는다.
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `test:unit`(FE-GATE-005)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+17
View File
@@ -0,0 +1,17 @@
# AGENTS.md — `src/presentation` (일반 UI와 들어오는 adapter)
라우트, 레이아웃, 디자인 시스템, 페이지, provider가 있다. 제품 기능이 아닌 일반 UI다.
## 지킬 것
- adapter·bootstrap을 import하지 않는다(`presentation-does-not-know-adapters`, 예외 `presentation/adapters/query`). 직접 fetch하지 않는다(`presentation-does-not-fetch-directly`).
- 페이지 템플릿은 레이아웃만 가진다(`page-templates-own-layout-only`). 설치된 제품 기능은 정해진 파일만 조립한다(`generic-presentation-does-not-compose-the-product`). apps·contexts를 import하지 않는다(라우터 하나 예외).
- 디자인 시스템은 `src/presentation/design-system/index.ts`로만 들어간다. 토큰 밖 색·간격을 쓰지 않는다(`docs/styling/design-tokens.md`).
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
## 검사
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:design-system`·`check:i18n`(FE-GATE-010 안)
- `test:component`(FE-GATE-006), e2e·접근성(FE-GATE-008·009), 시각 골든(`tests/visual/`)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/component`, `tests/e2e`, `tests/visual`에 둔다(`.claude/rules/tests.md`).
+1
View File
@@ -0,0 +1 @@
@AGENTS.md