From a55374927f4125ce65f4ff3b6bf0a23b4d9ade9f Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:03:48 +0900 Subject: [PATCH 01/10] docs(harness): add docs/agent/skills.md as skills inventory canonical (#561) --- docs/agent/skills.md | 95 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/agent/skills.md diff --git a/docs/agent/skills.md b/docs/agent/skills.md new file mode 100644 index 00000000..30ac640e --- /dev/null +++ b/docs/agent/skills.md @@ -0,0 +1,95 @@ +--- +title: Skills inventory +owner: human +status: approved +updated: 2026-05-21 +tags: [agent, harness, skills] +related: + - AGENTS.md + - docs/wiki/schema/ownership-matrix.md +--- + +# Skills inventory + +monorepo에서 사용 가능한 slash command / skill의 정본. `CLAUDE.md`, `AGENTS.md`, `WARP.md`는 이 문서를 가리키기만 한다. + +## gstack (Software Factory) + +Sprint workflow: **Think → Plan → Build → Review → Test → Ship → Reflect**. + +| Phase | Command | Role | +| ------- | -------------------------------------------- | ----------------------------------------- | +| Think | `/office-hours` | YC Office Hours — reframe the product | +| Plan | `/plan-ceo-review` | CEO — rethink scope | +| Plan | `/plan-eng-review` | Eng Manager — lock architecture | +| Plan | `/plan-design-review` | Designer — rate & improve design | +| Plan | `/design-consultation` | Design Partner — build design system | +| Plan | `/autoplan` | Auto-review pipeline: CEO → design → eng | +| Build | `/browse` | Browser automation (Playwright) | +| Review | `/review` | Staff Engineer — find production bugs | +| Review | `/design-review` | Designer Who Codes — audit + fix | +| Review | `/cso` | Security Officer — OWASP + STRIDE audit | +| Test | `/qa` | QA Lead — real browser testing + auto-fix | +| Test | `/qa-only` | QA report only (no fixes) | +| Ship | `/ship` | Release Engineer — test, PR, ship | +| Ship | `/land-and-deploy` | Merge → deploy → canary verify | +| Monitor | `/canary` | Post-deploy monitoring | +| Monitor | `/benchmark` | Performance regression detection | +| Debug | `/investigate` | Systematic root-cause debugging | +| Reflect | `/retro` | Sprint retrospective | +| Docs | `/document-release` | Post-ship doc updates | +| Safety | `/careful`, `/freeze`, `/guard`, `/unfreeze` | Destructive op protection | +| Setup | `/setup-deploy`, `/setup-browser-cookies` | One-time config | +| Utility | `/gstack-upgrade` | Update gstack | +| Utility | `/codex` | Multi-AI second opinion | +| Utility | `/connect-chrome` | Connect Chrome for browsing | + +### Rules + +- 웹 브라우징은 항상 `/browse` 사용 — `mcp__claude-in-chrome__*` 금지 +- gstack 스킬이 동작하지 않으면 `cd ~/.claude/skills/gstack && ./setup` +- Sprint 순서 준수: Think → Plan → Build → Review → Test → Ship → Reflect + +## Matt Pocock slash commands + +| Command | 용도 | +| -------------------- | ------------------------------------------------------------------------------------------- | +| `/grill` | plan/design을 인터뷰로 결정 분기 풀기 | +| `/grill-docs` | plan을 도메인 모델·ADR과 함께 grill | +| `/to-prd` | 대화 맥락을 PRD로 응축해 issue tracker에 publish | +| `/to-issues` | plan/PRD를 vertical slice GitHub Issues로 분해 | +| `/zoom-out` | 현재 코드/맥락을 더 넓은 시야로 다시 보기 | +| `/setup-matt-skills` | issue tracker / triage labels / domain docs 위치를 AGENTS.md·CLAUDE.md에 등록 (1회성 setup) | + +## Spec / Generator skills + +| Trigger 키워드 | Skill | +| --------------------------------------------------------- | ---------------------------- | +| "screen spec", "화면 명세", "document screen" | screen-spec-generator | +| "data model", "generate types", "create interface" | data-model-generator | +| "API contract", "OpenAPI", "endpoint spec" | api-contract-generator | +| "scaffold component", "create component", "컴포넌트 생성" | component-template-generator | +| "migration", "database schema", "테이블 생성" | supabase-migration-generator | +| "excalidraw", "다이어그램", "flowchart", "ERD" | excalidraw-generator | +| "pencil ui", "screen ui", "디자인 구현", "UI 구현" | pencil-screen-ui | +| "meeting prep", "weekly update", "주간 보고" | meeting-prep | +| "브랜치 이름", "commit convention", "PR 준비" | git-workflow | + +## Skill routing rules + +사용자의 요청이 가용 skill과 매치되면 **Skill tool을 FIRST action으로** 호출. 직접 답하지 않는다. + +핵심 라우팅: + +- Product ideas, "is this worth building", brainstorming → `office-hours` +- Bugs, errors, "why is this broken", 500 errors → `investigate` +- Ship, deploy, push, create PR → `ship` +- QA, test the site, find bugs → `qa` +- Code review, check my diff → `review` +- Update docs after shipping → `document-release` +- Weekly retro → `retro` +- Design system, brand → `design-consultation` +- Visual audit, design polish → `design-review` +- Architecture review → `plan-eng-review` +- Save progress, checkpoint, resume → `checkpoint` +- Code quality, health check → `health` From 0e412f3d75d76d4ba2189e135ac6b5b9f52ba0c0 Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:04:09 +0900 Subject: [PATCH 02/10] docs(plan): add #561 harness docs/wiki SSOT implementation plan --- .../plans/2026-05-21-561-harness-docs-ssot.md | 1112 +++++++++++++++++ 1 file changed, 1112 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-21-561-harness-docs-ssot.md diff --git a/docs/superpowers/plans/2026-05-21-561-harness-docs-ssot.md b/docs/superpowers/plans/2026-05-21-561-harness-docs-ssot.md new file mode 100644 index 00000000..453777b5 --- /dev/null +++ b/docs/superpowers/plans/2026-05-21-561-harness-docs-ssot.md @@ -0,0 +1,1112 @@ +# #561 — Agent-facing docs/wiki SSOT 정리 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** monorepo의 agent 진입점이 7곳(CLAUDE.md / AGENTS.md / AGENT.md / WARP.md / docs/agent/README.md / docs/agents/ / .cursor/rules)으로 shallow하게 흩어지고 routing 테이블 사본이 drift한 문제를, `AGENTS.md`를 cross-tool canonical로 격상하고 `docs/wiki/schema/ownership-matrix.md`를 routing SSOT로 만들어 해결한다. + +**Architecture:** (a) `AGENTS.md` = canonical cross-tool 진입점(Codex / Cursor / Warp / Claude 공통), 나머지 entry 파일은 overlay/redirect. (b) `ownership-matrix.md`에 5개 새 row(ADR · Harness wiki · Skills inventory · Cross-tool agent entry · Vault contract)를 추가해 모든 routing의 정본으로 격상. (c) `docs/agents/` 폴더는 `docs/agent/setup/`으로 흡수. (d) ADR canonical은 vault `Architecture/adr/`로 일원화, monorepo `docs/adr/`는 redirect index만. (e) Deprecated artifact는 `docs/_archive/`로. + +**Tech Stack:** Markdown, `gh` CLI, `grep`/`rg`, shell. 빌드/테스트 없음 — 검증은 grep + 파일 존재 체크. + +**Scope note:** PR 단위는 아래 그룹으로 분리한다. + +- **PR-A**: Task 1~3 (entry SSOT + ownership-matrix + 폴더 통합) +- **PR-B**: Task 4 (ADR vault 일원화 + ADR-0003 vault 측 draft 가이드) +- **PR-C**: Task 5~6 (archive + INDEX.md 정정) + +--- + +## File Structure + +**Create:** + +- `docs/superpowers/plans/2026-05-21-561-harness-docs-ssot.md` (이 파일) +- `docs/agent/skills.md` — gstack · Matt Pocock · Spec/Generator 표의 정본 +- `docs/agent/setup/issue-tracker.md` ← `docs/agents/issue-tracker.md` 이동 +- `docs/agent/setup/triage-labels.md` ← `docs/agents/triage-labels.md` 이동 +- `docs/agent/setup/domain.md` ← `docs/agents/domain.md` 이동 +- `docs/adr/index.md` — ADR canonical은 vault, monorepo는 redirect +- `docs/_archive/README.md` — archive 정책 명시 +- `docs/_archive/warehouse-schema.md` ← `docs/agent/warehouse-schema.md` 이동 + +**Modify:** + +- `AGENTS.md` (6 → ~80줄) — canonical cross-tool 명세로 확장 +- `CLAUDE.md` (241 → ≤80줄) — Claude Code overlay로 축소 +- `WARP.md` — Warp overlay 패턴 정렬 (AGENTS.md를 먼저 가리키도록) +- `AGENT.md` (37 → ~5줄) — AGENTS.md 1줄 redirect +- `.cursor/rules/monorepo.mdc` — AGENTS.md를 먼저 가리키도록 헤더 추가 +- `docs/agent/README.md` — `setup/` 섹션 추가, archived 항목 제거, "Skills inventory: `skills.md`" 추가 +- `docs/wiki/schema/ownership-matrix.md` — 5개 row 추가 +- `docs/wiki/wiki/INDEX.md` — "Sub-3 ingest 자동 등재" 문구 제거, 빈 카테고리 안내 +- `docs/adr/ADR-0001-ai-dev-boilerplate.md` — vault stub로 변경 (외부 link 호환) +- `docs/adr/ADR-0002-llm-wiki-foundation.md` — vault stub로 변경 + +**Delete:** + +- `docs/agents/` 디렉터리 전체 (3개 파일은 이동 완료 후) +- `docs/agent/warehouse-schema.md` (archive로 이동 후) + +--- + +## Pre-flight Verification + +- [ ] **Step 0.1: 현재 워크트리 상태 확인** + +Run: + +```bash +git branch --show-current +git log -1 --oneline +``` + +Expected: branch `chore/561-harness-docs-ssot`, HEAD = `baabae4c chore(harness): audit #558 후속 정리 ...` (origin/dev tip) + +- [ ] **Step 0.2: docs/agents/ 존재 확인** + +Run: `ls docs/agents/` +Expected: `domain.md issue-tracker.md triage-labels.md` + +- [ ] **Step 0.3: 영향 받는 파일 목록 grep** + +Run: + +```bash +rg -l "docs/agents/" --type md +rg -l "docs/agent/warehouse-schema" --type md +``` + +Expected: monorepo 전체에서 어떤 파일들이 영향받는지 미리 확인 (CLAUDE.md, ADR 등). + +--- + +## PR-A: Entry SSOT + ownership-matrix + 폴더 통합 + +### Task 1: `docs/agent/skills.md` 신설 — Skills inventory 정본 + +**Files:** + +- Create: `docs/agent/skills.md` + +CLAUDE.md의 inline skill 표(gstack 30+ 스킬, Matt Pocock 슬래시 커맨드, Spec/Generator skills)는 drift 위험이 크므로 별도 정본으로 분리한다. + +- [ ] **Step 1.1: skills.md 작성** + +```markdown +--- +title: Skills inventory +owner: human +status: approved +updated: 2026-05-21 +tags: [agent, harness, skills] +related: + - AGENTS.md + - docs/wiki/schema/ownership-matrix.md +--- + +# Skills inventory + +monorepo에서 사용 가능한 slash command / skill의 정본. `CLAUDE.md`, `AGENTS.md`, `WARP.md`는 이 문서를 가리키기만 한다. + +## gstack (Software Factory) + +Sprint workflow: **Think → Plan → Build → Review → Test → Ship → Reflect**. + +| Phase | Command | Role | +| ------- | -------------------------------------------- | ----------------------------------------- | +| Think | `/office-hours` | YC Office Hours — reframe the product | +| Plan | `/plan-ceo-review` | CEO — rethink scope | +| Plan | `/plan-eng-review` | Eng Manager — lock architecture | +| Plan | `/plan-design-review` | Designer — rate & improve design | +| Plan | `/design-consultation` | Design Partner — build design system | +| Plan | `/autoplan` | Auto-review pipeline: CEO → design → eng | +| Build | `/browse` | Browser automation (Playwright) | +| Review | `/review` | Staff Engineer — find production bugs | +| Review | `/design-review` | Designer Who Codes — audit + fix | +| Review | `/cso` | Security Officer — OWASP + STRIDE audit | +| Test | `/qa` | QA Lead — real browser testing + auto-fix | +| Test | `/qa-only` | QA report only (no fixes) | +| Ship | `/ship` | Release Engineer — test, PR, ship | +| Ship | `/land-and-deploy` | Merge → deploy → canary verify | +| Monitor | `/canary` | Post-deploy monitoring | +| Monitor | `/benchmark` | Performance regression detection | +| Debug | `/investigate` | Systematic root-cause debugging | +| Reflect | `/retro` | Sprint retrospective | +| Docs | `/document-release` | Post-ship doc updates | +| Safety | `/careful`, `/freeze`, `/guard`, `/unfreeze` | Destructive op protection | +| Setup | `/setup-deploy`, `/setup-browser-cookies` | One-time config | +| Utility | `/gstack-upgrade` | Update gstack | +| Utility | `/codex` | Multi-AI second opinion | +| Utility | `/connect-chrome` | Connect Chrome for browsing | + +### Rules + +- 웹 브라우징은 항상 `/browse` 사용 — `mcp__claude-in-chrome__*` 금지 +- gstack 스킬이 동작하지 않으면 `cd ~/.claude/skills/gstack && ./setup` +- Sprint 순서 준수: Think → Plan → Build → Review → Test → Ship → Reflect + +## Matt Pocock slash commands + +| Command | 용도 | +| -------------------- | ------------------------------------------------------------------------------------------- | +| `/grill` | plan/design을 인터뷰로 결정 분기 풀기 | +| `/grill-docs` | plan을 도메인 모델·ADR과 함께 grill | +| `/to-prd` | 대화 맥락을 PRD로 응축해 issue tracker에 publish | +| `/to-issues` | plan/PRD를 vertical slice GitHub Issues로 분해 | +| `/zoom-out` | 현재 코드/맥락을 더 넓은 시야로 다시 보기 | +| `/setup-matt-skills` | issue tracker / triage labels / domain docs 위치를 AGENTS.md·CLAUDE.md에 등록 (1회성 setup) | + +## Spec / Generator skills + +| Trigger 키워드 | Skill | +| --------------------------------------------------------- | ---------------------------- | +| "screen spec", "화면 명세", "document screen" | screen-spec-generator | +| "data model", "generate types", "create interface" | data-model-generator | +| "API contract", "OpenAPI", "endpoint spec" | api-contract-generator | +| "scaffold component", "create component", "컴포넌트 생성" | component-template-generator | +| "migration", "database schema", "테이블 생성" | supabase-migration-generator | +| "excalidraw", "다이어그램", "flowchart", "ERD" | excalidraw-generator | +| "pencil ui", "screen ui", "디자인 구현", "UI 구현" | pencil-screen-ui | +| "meeting prep", "weekly update", "주간 보고" | meeting-prep | +| "브랜치 이름", "commit convention", "PR 준비" | git-workflow | + +## Skill routing rules + +사용자의 요청이 가용 skill과 매치되면 **Skill tool을 FIRST action으로** 호출. 직접 답하지 않는다. + +핵심 라우팅: + +- Product ideas, "is this worth building", brainstorming → `office-hours` +- Bugs, errors, "why is this broken", 500 errors → `investigate` +- Ship, deploy, push, create PR → `ship` +- QA, test the site, find bugs → `qa` +- Code review, check my diff → `review` +- Update docs after shipping → `document-release` +- Weekly retro → `retro` +- Design system, brand → `design-consultation` +- Visual audit, design polish → `design-review` +- Architecture review → `plan-eng-review` +- Save progress, checkpoint, resume → `checkpoint` +- Code quality, health check → `health` +``` + +- [ ] **Step 1.2: 파일 존재 검증** + +Run: `wc -l docs/agent/skills.md && head -10 docs/agent/skills.md` +Expected: 60+ lines, frontmatter `title: Skills inventory` 포함. + +- [ ] **Step 1.3: Commit** + +```bash +git add docs/agent/skills.md +git commit -m "docs(harness): add docs/agent/skills.md as skills inventory canonical (#561)" +``` + +--- + +### Task 2: `AGENTS.md`를 canonical cross-tool 명세로 확장 + +**Files:** + +- Modify: `AGENTS.md` (6 → ~80줄) + +- [ ] **Step 2.1: AGENTS.md 전면 재작성** + +```markdown +# AGENTS.md — Cross-tool agent entry point + +이 파일은 monorepo의 **canonical agent 진입점**이다. 모든 LLM 도구(Codex / Cursor / Warp / Claude Code / Gemini CLI)는 작업 시작 시 이 파일을 **가장 먼저** 읽는다. + +각 도구별 overlay는 본 파일을 보강만 한다 — 본 파일과 충돌하면 본 파일이 우선한다. + +## 도구별 overlay 매핑 + +| 도구 | Overlay 파일 | 역할 | +| ----------------- | ---------------------- | --------------------------------------------------------------- | +| Claude Code | `CLAUDE.md` | Claude Code 전용 routing 규칙(skill, OMC, GSD, Superpowers) | +| Warp Terminal | `WARP.md` | Warp 워크플로우 명령·자동화 | +| Cursor | `.cursor/rules/*.mdc` | Cursor 네이티브 규칙(globs · description) | +| Codex CLI | `~/.codex/config.toml` | Hybrid harness Layer 2/2.5 (codex exec --profile fast / strict) | +| 한국어 진입(공통) | `AGENT.md` | `AGENTS.md` 1줄 redirect | + +## 읽기 우선순위 + +1. **AGENTS.md** (이 파일) — cross-tool 공통 +2. **`docs/wiki/schema/ownership-matrix.md`** — 정보 카테고리별 정본/pointer 매핑 SSOT +3. **`docs/agent/README.md`** — agent 참조 인벤토리 목차 (라우트, API, 훅, 디자인 시스템) +4. **`.planning/codebase/*`** — 스택·아키텍처·컨벤션·테스트 +5. 도구별 overlay (`CLAUDE.md`, `WARP.md`, `.cursor/rules`, ...) + +## Routing SSOT + +정보 카테고리별로 어디를 정본으로 보아야 하는지는 **`docs/wiki/schema/ownership-matrix.md`** 하나가 결정한다. 다른 파일은 그 행을 가리키기만 한다 — 표를 복제하지 않는다. + +대표 항목: + +- Stack/버전 → `.planning/codebase/STACK.md` +- 코딩 컨벤션 → `docs/wiki/schema/conventions.md` +- Skills inventory → **`docs/agent/skills.md`** +- ADR → vault `Architecture/adr/` (monorepo 측 stub: `docs/adr/index.md`) +- Harness wiki → `docs/wiki/wiki/harness/*` +- Cross-tool agent entry → 이 파일 + +전체 매트릭스: [`docs/wiki/schema/ownership-matrix.md`](docs/wiki/schema/ownership-matrix.md) + +## Documentation 위치 (decoded vs decoded-docs) + +| 종류 | 위치 | +| ----------------------------------------- | --------------------------------------------------------------------------------- | +| 코드 · LLM 라우팅 · agent 인벤토리 · spec | **이 레포** (`docs/agent/`, `docs/superpowers/`, `AGENTS.md`, 등) | +| 회의 · 결정 · 기획 · 아키텍처 · 회고 | **[decoded-docs vault](https://github.com/decodedcorp/decoded-docs)** (별도 레포) | + +전체 sync policy: [decoded-docs/Guides/sync-policy.md](https://github.com/decodedcorp/decoded-docs/blob/main/Guides/sync-policy.md) + +회사 지식 질의(예: "지난주 결정 뭐였어?")는 Telegram 매니저 agent에게 — vault 기반 답변. + +## 작업 유형별 진입 파일 + +| 작업 | 문서 | +| ------------------------------ | --------------------------------------- | +| 명령어·패키지 구조·로컬 deps | `docs/agent/monorepo.md` | +| 웹 라우트·기능 영역 | `docs/agent/web-routes-and-features.md` | +| Next.js `app/api/v1` | `docs/agent/api-v1-routes.md` | +| 훅·스토어 | `docs/agent/web-hooks-and-stores.md` | +| 디자인 시스템 import·컴포넌트 | `docs/agent/design-system-llm.md` | +| Skills · slash commands | `docs/agent/skills.md` | +| Setup (issue tracker · triage) | `docs/agent/setup/` | +| Rust API crate | `packages/api-server/AGENT.md` | +| 아키텍처·컨벤션·스택 심층 | `.planning/codebase/` | +| Harness 세션 규율 | `docs/wiki/wiki/harness/*` | + +## 반드시 지킬 것 + +1. **패키지 매니저**: **bun** (`bun run`, `bun add`). yarn/npm 아님. +2. **상세 표의 SSOT**: `docs/agent/` + `ownership-matrix.md` — overlay 파일에는 링크만. +3. **Git workflow**: `feature/*` → `dev` → `main`. `main` 직접 push 금지. 상세는 `docs/GIT-WORKFLOW.md`. +4. **Conventional Commits** 준수. +5. **Skill 라우팅**: 사용자 요청이 skill과 매치되면 Skill tool을 FIRST action으로. 직접 답하지 않는다. 상세는 `docs/agent/skills.md`. +6. **Generated 코드 금지**: `packages/web/lib/api/generated/`는 Orval 자동 생성, 수동 편집 금지. +7. **Vault 결정**: 회의·결정·아키텍처·회고는 monorepo에 두지 않는다 — 항상 vault. + +## Harness Workflow + +| Tool | Role | When | +| ----------- | -------------------- | ------------------- | +| gstack | 기획/리뷰/QA/배포 | Think → Plan → Ship | +| Superpowers | TDD, 코드 품질 강제 | Build (구현) | +| OMC | Claude + Gemini 듀얼 | 대규모 작업 보조 | +| GSD quick | 원자적 단발 패치 | 유지보수 | + + +``` + +- [ ] **Step 2.2: 검증** + +Run: + +```bash +wc -l AGENTS.md +grep -c "^##" AGENTS.md +``` + +Expected: 80~100줄, 섹션 헤더 7~10개. + +- [ ] **Step 2.3: Commit** + +```bash +git add AGENTS.md +git commit -m "docs(harness): expand AGENTS.md as canonical cross-tool entry (#561)" +``` + +--- + +### Task 3: `CLAUDE.md`를 Claude Code overlay로 축소 (≤80줄) + +**Files:** + +- Modify: `CLAUDE.md` (241 → ≤80줄) + +CLAUDE.md는 Claude Code 전용 overlay로만 남기고, inline 표(gstack/Matt Pocock/Spec generator/Skill routing)는 모두 `docs/agent/skills.md`로 위임한다. 일반 진입 규칙은 `AGENTS.md`로 위임한다. + +- [ ] **Step 3.1: CLAUDE.md 전면 재작성** + +````markdown +# CLAUDE.md — Claude Code overlay + +> 본 파일은 **Claude Code 전용 overlay**다. 공통 cross-tool 진입 규칙은 **`AGENTS.md`를 먼저 읽고**, 본 파일은 Claude Code-specific 보강만 담는다. + +## Read order + +1. `AGENTS.md` (canonical, cross-tool) +2. `docs/wiki/schema/ownership-matrix.md` (routing SSOT) +3. 본 파일 (Claude Code overlay) +4. `docs/agent/README.md` (참조 인벤토리) + +## Documentation 위치 + +코드/LLM 라우팅/agent 인벤토리/spec은 monorepo. 회의/결정/아키텍처/회고는 vault — 자세한 사항은 `AGENTS.md` 참조. + +## Skill routing (Claude Code) + +사용자 요청이 가용 skill과 매치되면 Skill tool을 **FIRST action**으로 호출한다. 표/세부 매핑은 **`docs/agent/skills.md`**가 정본. + +핵심 라우팅 키워드: + +- "is this worth building" / brainstorming → `office-hours` +- bug / 500 → `investigate` +- ship / deploy / PR → `ship` +- QA → `qa` +- code review → `review` +- design system → `design-consultation` +- save progress → `checkpoint` + +## Commit discipline (Claude Code) + +- 작업 완료 시 검증 후 관련 파일만 선별해 커밋. 커밋 금지는 push/merge/PR 병합 금지와 구분 — 로컬 커밋은 기본 완료 조건. +- 더러운 워크트리에서는 unrelated 변경 건드리지 말고 `git add `만. +- review-only / plan-only 모드, human checkpoint 필요 작업이면 커밋하지 않고 이유 남김. + +## Worktree + +세션 격리는 `superpowers:using-git-worktrees` 사용. `.claude/worktrees/`는 `.gitignore`됨. + +## GSD Workflow (quick reference) + +```bash +/gsd:quick # 빠른 작업 +/gsd:progress # 전체 진행 상황 +/gsd:help # 명령어 목록 +``` +```` + +자세한 GSD/gstack/Superpowers 경계는 `AGENTS.md`의 Harness Workflow 표 참조. + + + + + +- [Antigravity Rules](file:///Users/kiyeol/development/decoded/decoded-app/.antigravity/rules.md) — Autonomous execution policy and language preferences. + + +```` + +- [ ] **Step 3.2: 라인 수 검증** + +Run: `wc -l CLAUDE.md` +Expected: 60~80줄. + +- [ ] **Step 3.3: Commit** + +```bash +git add CLAUDE.md +git commit -m "docs(harness): shrink CLAUDE.md to Claude Code overlay (#561)" +```` + +--- + +### Task 4: `WARP.md`를 Warp overlay 패턴으로 정렬 + +**Files:** + +- Modify: `WARP.md` + +- [ ] **Step 4.1: WARP.md 상단에 "Read AGENTS.md first" 헤더 추가** + +WARP.md의 **첫 번째 헤더 바로 다음**에 다음 블록을 삽입: + +```markdown +> 본 파일은 **Warp Terminal 전용 overlay**다. 공통 cross-tool 진입 규칙은 **`AGENTS.md`를 먼저 읽고**, 본 파일은 Warp-specific 보강(워크플로우 명령·자동화)만 담는다. +> +> Read order: `AGENTS.md` → `docs/wiki/schema/ownership-matrix.md` → 본 파일. +``` + +- [ ] **Step 4.2: WARP.md 중복 표 제거** + +WARP.md 안에 `AGENTS.md`/`CLAUDE.md`와 중복되는 routing 표(Documentation 위치, Harness Workflow, Skill routing 등)가 있으면 제거하고 "→ AGENTS.md 참조" 1줄로 대체. + +검증 grep: + +```bash +grep -E "(Documentation 위치|Harness Workflow|Skill routing)" WARP.md +``` + +Expected: 매치 0건 (또는 "→ AGENTS.md" 형태만). + +- [ ] **Step 4.3: Commit** + +```bash +git add WARP.md +git commit -m "docs(harness): align WARP.md as Warp overlay, defer common rules to AGENTS.md (#561)" +``` + +--- + +### Task 5: `.cursor/rules/*.mdc`에 AGENTS.md redirect 헤더 추가 + +**Files:** + +- Modify: `.cursor/rules/monorepo.mdc`, `.cursor/rules/api-routes.mdc`, `.cursor/rules/react-components.mdc`, `.cursor/rules/rust-api.mdc` + +- [ ] **Step 5.1: 각 .mdc 파일 상단(frontmatter 다음)에 1줄 추가** + +각 파일의 frontmatter 블록 다음에 다음을 삽입: + +```markdown +> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지. +``` + +검증: + +```bash +for f in .cursor/rules/*.mdc; do + echo "=== $f ===" + head -10 "$f" +done +``` + +- [ ] **Step 5.2: Commit** + +```bash +git add .cursor/rules/*.mdc +git commit -m "docs(harness): point .cursor/rules to AGENTS.md as common entry (#561)" +``` + +--- + +### Task 6: `AGENT.md`를 AGENTS.md 1줄 redirect로 축소 + +**Files:** + +- Modify: `AGENT.md` (37 → ~5줄) + +- [ ] **Step 6.1: AGENT.md 재작성** + +```markdown +# AGENT.md — 한국어 진입점 (redirect) + +본 파일은 `AGENTS.md`로 합쳐졌다. 한국어 작업 메모를 포함한 cross-tool 진입 규칙은 **[`AGENTS.md`](AGENTS.md)** 를 읽는다. + +(파일 자체는 외부 link 호환을 위해 유지.) +``` + +- [ ] **Step 6.2: Commit** + +```bash +git add AGENT.md +git commit -m "docs(harness): redirect AGENT.md to AGENTS.md (#561)" +``` + +--- + +### Task 7: `docs/wiki/schema/ownership-matrix.md`에 5개 row 추가 + +**Files:** + +- Modify: `docs/wiki/schema/ownership-matrix.md` + +- [ ] **Step 7.1: 매트릭스 표 끝에 5개 row 추가** + +`docs/wiki/schema/ownership-matrix.md`의 매트릭스 표(line 34) 끝에 다음 5개 row를 추가: + +```markdown +| ADR (Architectural Decisions) | vault `Architecture/adr/` | `docs/adr/index.md` | +| Harness wiki (세션 규율) | `docs/wiki/wiki/harness/*` | `AGENTS.md`, `docs/agent/README.md` | +| Skills inventory (gstack/Matt/Spec) | `docs/agent/skills.md` | `AGENTS.md`, `CLAUDE.md`, `WARP.md` | +| Cross-tool agent entry (도구별 overlay 매핑) | `AGENTS.md` | `CLAUDE.md`, `WARP.md`, `.cursor/rules/*.mdc`, `AGENT.md` | +| Vault contract (3-repo ecosystem) | vault `Guides/sync-policy.md` + ADR-0003 | `docs/wiki/schema/ownership-matrix.md` (본 파일) | +``` + +- [ ] **Step 7.2: 프론트매터 `updated` 갱신** + +```yaml +updated: 2026-05-21 +``` + +- [ ] **Step 7.3: 원칙 섹션 보강** + +원칙 섹션 끝에 다음 항목 추가: + +```markdown +5. **ADR canonical은 vault**. monorepo `docs/adr/`는 redirect index만 유지한다. 자세한 결정은 ADR-0003 참조. +6. **Cross-tool entry**의 정본은 `AGENTS.md`. Claude/Warp/Cursor overlay는 본 파일을 가리킨다. +``` + +- [ ] **Step 7.4: Commit** + +```bash +git add docs/wiki/schema/ownership-matrix.md +git commit -m "docs(harness): promote ownership-matrix to routing SSOT, add 5 new rows (#561)" +``` + +--- + +### Task 8: `docs/agents/` → `docs/agent/setup/` 이동 + +**Files:** + +- Create: `docs/agent/setup/issue-tracker.md`, `docs/agent/setup/triage-labels.md`, `docs/agent/setup/domain.md` +- Delete: `docs/agents/` 디렉터리 + +- [ ] **Step 8.1: `setup/` 디렉터리 생성 + git mv** + +```bash +mkdir -p docs/agent/setup +git mv docs/agents/issue-tracker.md docs/agent/setup/issue-tracker.md +git mv docs/agents/triage-labels.md docs/agent/setup/triage-labels.md +git mv docs/agents/domain.md docs/agent/setup/domain.md +rmdir docs/agents 2>/dev/null || true +``` + +검증: + +```bash +ls docs/agent/setup/ +ls docs/agents/ 2>&1 +``` + +Expected: 3개 파일이 setup/에 있고 docs/agents/는 "No such file". + +- [ ] **Step 8.2: `docs/agent/README.md`에 setup 섹션 추가** + +`docs/agent/README.md`의 표 끝(line 38, "디자인 토큰·UI 상세" row 다음) 또는 별도 ## Setup 섹션 신설: + +```markdown +## Setup (1회성) + +| 항목 | 문서 | +| ---------------- | ------------------------------------------------ | +| Issue tracker | [setup/issue-tracker.md](setup/issue-tracker.md) | +| Triage labels | [setup/triage-labels.md](setup/triage-labels.md) | +| Domain docs 위치 | [setup/domain.md](setup/domain.md) | +| Skills inventory | [skills.md](skills.md) | +``` + +- [ ] **Step 8.3: 잔존 `docs/agents/` 참조 일괄 치환** + +```bash +rg -l "docs/agents/" --type md +# 매치 파일에 대해 sed로 치환 +rg -l "docs/agents/" --type md | xargs -I{} sed -i '' 's|docs/agents/|docs/agent/setup/|g' {} +``` + +(macOS는 `sed -i ''`, GNU sed는 `sed -i`.) + +검증: + +```bash +rg "docs/agents/" --type md +``` + +Expected: 매치 0건. + +- [ ] **Step 8.4: 빌드/링크 검증 (optional)** + +Run: + +```bash +# 단순 파일 존재 체크 +for f in docs/agent/setup/issue-tracker.md docs/agent/setup/triage-labels.md docs/agent/setup/domain.md; do + test -f "$f" && echo "OK $f" || echo "MISSING $f" +done +``` + +- [ ] **Step 8.5: Commit** + +```bash +git add docs/agent/setup/ docs/agent/README.md AGENTS.md CLAUDE.md +# (Task 8.3에서 sed가 건드린 모든 파일 포함) +git add -u +git commit -m "docs(harness): merge docs/agents/ into docs/agent/setup/ (#561)" +``` + +--- + +### Task 9: PR-A draft PR 생성 + audit + +- [ ] **Step 9.1: 전체 grep 검증** + +```bash +echo "== docs/agents/ 잔존 ==" && rg "docs/agents/" --type md +echo "== AGENTS.md 단독 진입 시뮬레이션 ==" && head -50 AGENTS.md +echo "== ownership-matrix 행 수 ==" && grep -c "^|" docs/wiki/schema/ownership-matrix.md +``` + +Expected: docs/agents/ 0건, ownership-matrix 행 수 = 헤더 1 + 구분 1 + 본문 14+5 = 21. + +- [ ] **Step 9.2: 변경 파일 요약** + +```bash +git log --oneline origin/dev..HEAD +git diff --stat origin/dev..HEAD +``` + +- [ ] **Step 9.3: PR 본문 작성 + Draft push** + +본 명령은 **사용자 명시적 승인 후** 실행: + +```bash +git push -u origin chore/561-harness-docs-ssot +gh pr create --base dev --draft \ + --title "chore(harness): entry SSOT + ownership-matrix + folder unify (#561 PR-A)" \ + --body-file <(cat <<'EOF' +## Summary + +#561 Sub-task #1·#2·#3 — agent 진입점 통합 + ownership-matrix routing SSOT 격상 + `docs/agents/` ↔ `docs/agent/setup/` 통합. + +- [x] `AGENTS.md`를 canonical cross-tool 진입점으로 확장 +- [x] `CLAUDE.md`를 Claude Code overlay로 축소(≤80줄) +- [x] `WARP.md`/`.cursor/rules/*.mdc`/`AGENT.md`를 overlay/redirect로 정렬 +- [x] `docs/agent/skills.md` 신설, CLAUDE.md inline 표 위임 +- [x] `docs/wiki/schema/ownership-matrix.md`에 5개 row 추가 +- [x] `docs/agents/` → `docs/agent/setup/` 이동, 잔존 참조 0건 + +## Verification + +- `rg "docs/agents/" --type md` → 0건 +- AGENTS.md 단독으로 cross-tool 진입 가능 (Codex / Cursor / Warp 시뮬레이션 통과) +- ownership-matrix와 잔존 inventory drift 0건 + +## Linked + +Closes part of #561 (Sub-task #1, #2, #3). + +다음 PR(PR-B)는 ADR vault 일원화(#4·#6), PR-C는 archive + INDEX.md 정정(#5·#7). +EOF +) +``` + +--- + +## PR-B: ADR vault 일원화 + +### Task 10: `docs/adr/index.md` 신설 + +**Files:** + +- Create: `docs/adr/index.md` + +- [ ] **Step 10.1: index.md 작성** + +```markdown +--- +title: ADR Index (redirect to vault) +owner: human +status: approved +updated: 2026-05-21 +tags: [adr, harness] +--- + +# Architectural Decision Records (ADR) + +**Canonical 위치는 vault**: [`decoded-docs/Architecture/adr/`](https://github.com/decodedcorp/decoded-docs/tree/main/Architecture/adr) + +monorepo의 `docs/adr/` 폴더는 외부 link 호환을 위한 redirect stub만 유지한다. + +## 최근 ADR + +| ID | Title | Status | +| -------- | ----------------------------------------------------------------------------------------------- | -------- | +| ADR-0001 | AI dev boilerplate (vault) | approved | +| ADR-0002 | LLM Wiki foundation (vault) | approved | +| ADR-0003 | Cross-tool agent entry policy (#561) — 본 ADR이 cross-tool entry/ownership-matrix 정책을 본문화 | proposed | + +## 정책 + +- 새 ADR은 vault `Architecture/adr/ADR-XXXX-.md`에 작성한다. +- monorepo의 `docs/adr/ADR-XXXX-*.md`는 vault link 1줄만 가진 stub로 유지한다 (외부 link rot 방지). +- 자세한 vault sync policy는 [`Guides/sync-policy.md`](https://github.com/decodedcorp/decoded-docs/blob/main/Guides/sync-policy.md). +``` + +- [ ] **Step 10.2: Commit** + +```bash +git add docs/adr/index.md +git commit -m "docs(adr): add monorepo index pointing to vault canonical (#561)" +``` + +--- + +### Task 11: 기존 ADR-0001/0002를 vault stub로 변경 + +**Files:** + +- Modify: `docs/adr/ADR-0001-ai-dev-boilerplate.md`, `docs/adr/ADR-0002-llm-wiki-foundation.md` + +- [ ] **Step 11.1: 기존 본문 백업 → vault 이동 (vault 측은 PR-B와 별도 작업)** + +```bash +# vault PR 작성 시 참조할 수 있도록 백업 +mkdir -p /tmp/561-adr-backup +cp docs/adr/ADR-0001-ai-dev-boilerplate.md /tmp/561-adr-backup/ +cp docs/adr/ADR-0002-llm-wiki-foundation.md /tmp/561-adr-backup/ +``` + +- [ ] **Step 11.2: ADR-0001 stub로 치환** + +```markdown +--- +title: ADR-0001 — AI dev boilerplate (redirect to vault) +status: superseded-by-vault +updated: 2026-05-21 +--- + +# ADR-0001 — AI dev boilerplate + +Canonical 위치는 vault: [`decoded-docs/Architecture/adr/ADR-0001-ai-dev-boilerplate.md`](https://github.com/decodedcorp/decoded-docs/blob/main/Architecture/adr/ADR-0001-ai-dev-boilerplate.md) + +(monorepo 측 본 파일은 외부 link 호환용 stub. vault 측이 정본.) +``` + +- [ ] **Step 11.3: ADR-0002 동일 패턴으로 치환** + +```markdown +--- +title: ADR-0002 — LLM Wiki foundation (redirect to vault) +status: superseded-by-vault +updated: 2026-05-21 +--- + +# ADR-0002 — LLM Wiki foundation + +Canonical 위치는 vault: [`decoded-docs/Architecture/adr/ADR-0002-llm-wiki-foundation.md`](https://github.com/decodedcorp/decoded-docs/blob/main/Architecture/adr/ADR-0002-llm-wiki-foundation.md) + +(monorepo 측 본 파일은 외부 link 호환용 stub. vault 측이 정본.) +``` + +- [ ] **Step 11.4: 잔존 ADR 본문 참조 확인** + +```bash +rg -l "docs/adr/ADR-000[12]" --type md +``` + +참조 파일이 있으면 vault link로 갱신하거나 redirect stub를 통하도록 둔다(stub이 link를 제공하므로 보통 그대로 둬도 됨). + +- [ ] **Step 11.5: Commit** + +```bash +git add docs/adr/ADR-0001-ai-dev-boilerplate.md docs/adr/ADR-0002-llm-wiki-foundation.md +git commit -m "docs(adr): convert ADR-0001/0002 to vault redirect stubs (#561)" +``` + +--- + +### Task 12: ADR-0003 draft 가이드 (vault 측 작업 안내) + +**Files:** + +- 본 PR에서는 작성하지 않음. vault repo에 별도 PR로 작성한다. + +- [ ] **Step 12.1: vault 측 작업 안내 문서 작성** + +monorepo PR-B 본문에 다음 체크리스트를 포함: + +```markdown +## Vault 측 작업 (별도 PR) + +본 PR과 짝을 이루는 vault PR을 [decoded-docs](https://github.com/decodedcorp/decoded-docs)에 생성한다: + +- `Architecture/adr/ADR-0003-cross-tool-agent-entry-policy.md` 작성 +- 본문 포함 항목: + - **결정**: AGENTS.md를 cross-tool canonical, ownership-matrix를 routing SSOT로 격상 + - **3-repo ecosystem matrix**: + | Artifact | monorepo | decoded-docs (vault) | decoded-agent | + | ------------------------------- | ----------------------- | ---------------------------------- | ------------------- | + | Code, agent inventory, spec | **owns / exports** | references | consumes (Telegram) | + | Architectural decisions (ADR) | redirect stub only | **owns / exports** | references | + | Meeting · 결정 · 회고 | — | **owns / exports** | consumes (Telegram) | + | Cross-tool entry (AGENTS.md) | **owns / exports** | — | consumes | + | Telegram manager logic | — | knowledge source | **owns** | + - **Sync policy 링크**: `Guides/sync-policy.md` + - **Supersedes**: 본 ADR이 cross-tool entry/ownership-matrix 정책의 기반. +- ownership-matrix.md의 "ADR" / "Vault contract" row가 ADR-0003을 가리키도록 갱신 +``` + +- [ ] **Step 12.2: PR-B Draft 생성** + +```bash +git push -u origin chore/561-harness-docs-ssot # 이미 push되어 있으면 단순 push +gh pr create --base dev --draft \ + --title "docs(adr): unify ADR canonical to vault, monorepo stubs only (#561 PR-B)" \ + --body-file <(cat <<'EOF' +## Summary + +#561 Sub-task #4 + #6 — ADR canonical을 vault `Architecture/adr/`로 일원화. monorepo `docs/adr/`는 redirect stub만. + +- [x] `docs/adr/index.md` 신설 (vault link + 최근 ADR 표) +- [x] ADR-0001 / ADR-0002 를 vault redirect stub로 변경 +- [ ] (vault 측 별도 PR) ADR-0003 작성 — cross-tool agent entry policy + 3-repo ecosystem matrix + +## Verification + +- `docs/adr/index.md` 존재, vault link 유효 +- 기존 ADR 본문 백업: `/tmp/561-adr-backup/` (vault PR 작성 시 참조) + +## Linked + +Closes part of #561 (Sub-task #4 monorepo 측, #6 monorepo 측). Vault PR과 짝. +EOF +) +``` + +--- + +## PR-C: Archive 정리 + INDEX.md 정정 + +### Task 13: `docs/_archive/` 신설 + warehouse-schema 이동 + +**Files:** + +- Create: `docs/_archive/README.md`, `docs/_archive/warehouse-schema.md` +- Delete: `docs/agent/warehouse-schema.md` + +- [ ] **Step 13.1: `_archive/` 디렉터리 + README 생성** + +```bash +mkdir -p docs/_archive +``` + +`docs/_archive/README.md`: + +```markdown +--- +title: Archived docs +owner: human +status: approved +updated: 2026-05-21 +tags: [archive] +--- + +# `docs/_archive/` + +Deprecated 또는 superseded된 문서의 보관 디렉터리. 외부 link 호환을 위해 삭제하지 않고 여기로 이동한다. + +## 정책 + +- 새로 archive되는 파일의 frontmatter `status: archived`를 명시한다. +- archive된 파일은 `docs/agent/README.md` 인벤토리에서 제거한다. +- 본 디렉터리는 build/lint/index에서 제외된다(필요 시 `.gitignore` 또는 lint exclude 추가). + +## 현재 archived 항목 + +| 파일 | 사유 | Archive 일자 | +| --------------------- | ----------------------------------------- | ------------ | +| `warehouse-schema.md` | DEPRECATED (#333 — assets project로 대체) | 2026-05-21 | +``` + +- [ ] **Step 13.2: warehouse-schema 이동 + frontmatter status 변경** + +```bash +git mv docs/agent/warehouse-schema.md docs/_archive/warehouse-schema.md +``` + +`docs/_archive/warehouse-schema.md` 의 frontmatter에 `status: archived`를 추가/변경한다. (이미 deprecated 표시가 본문에 있을 수 있으므로 frontmatter만 갱신.) + +- [ ] **Step 13.3: 잔존 참조 갱신** + +```bash +rg -l "docs/agent/warehouse-schema" --type md +rg -l "docs/agent/warehouse-schema" --type md | xargs -I{} sed -i '' 's|docs/agent/warehouse-schema.md|docs/_archive/warehouse-schema.md|g' {} +rg "docs/agent/warehouse-schema" --type md +``` + +Expected 마지막 grep: 매치 0건. + +- [ ] **Step 13.4: `docs/agent/README.md` 인벤토리에서 warehouse-schema 행 제거** + +`docs/agent/README.md` 의 line 35(`Warehouse 스키마 ... warehouse-schema.md`) 행을 삭제. +대신 \_archive 디렉터리에 대한 1줄 안내 추가: + +```markdown +> Deprecated 문서는 [`docs/_archive/`](../_archive/)에 보관한다. +``` + +- [ ] **Step 13.5: 다른 후보 파일 검토 (해당 시 archive)** + +| 파일 | 검토 결과 (수동) | +| ------------------------------------------- | ------------------------------------ | +| `docs/post-centric-refactoring-summary.md` | TBD — 본문 확인 후 archive 여부 결정 | +| `docs/home-sections-backend-feasibility.md` | TBD — 본문 확인 후 archive 여부 결정 | +| `docs/backend-frontend-status.md` | TBD — 본문 확인 후 archive 여부 결정 | + +각 파일 본문을 빠르게 확인하고 (head -20), "현재 운영에 더 이상 참조되지 않음" 판단이면 같은 패턴으로 `_archive/`로 이동. 판단 보류 시 본 PR 범위에서 제외하고 별도 follow-up 이슈 등록. + +`docs/qa-screenshots/` 정책은 별도 follow-up으로 분리 (분기별 archive 등 TBD — 본 PR 범위 아님). + +- [ ] **Step 13.6: Commit** + +```bash +git add docs/_archive/ docs/agent/README.md +git add -u # warehouse-schema 이동 + sed로 바뀐 파일 stage +git commit -m "docs(archive): create docs/_archive/, move warehouse-schema (#561)" +``` + +--- + +### Task 14: `docs/wiki/wiki/INDEX.md` 인터페이스/구현 정렬 + +**Files:** + +- Modify: `docs/wiki/wiki/INDEX.md` + +- [ ] **Step 14.1: "Sub-3 ingest 자동 등재" 문구 제거 + 수동 유지 명시** + +`docs/wiki/wiki/INDEX.md`의 line 14: + +``` +`docs/wiki/wiki/**` 누적 노트의 목차. Sub-3 ingest 파이프라인이 신규/갱신 파일을 자동 등재한다. Phase 1에는 수동 항목만 존재. +``` + +를 다음으로 치환: + +``` +`docs/wiki/wiki/**` 누적 노트의 목차. **현재는 수동으로 유지**한다 (자동 ingest는 향후 검토 대상). 새 노트 추가 시 본 INDEX의 카테고리 섹션에 직접 행을 추가한다. +``` + +- [ ] **Step 14.2: 빈 카테고리 처리** + +`docs/wiki/wiki/INDEX.md`의 line 23~29 (`## (비어 있음)` 섹션). 다음 중 하나로 선택: + +**Option A — 카테고리 섹션 자체를 제거 (Recommended):** + +```markdown +## 향후 카테고리 (TBD) + +다음 카테고리는 필요해질 때 본 INDEX에 섹션으로 추가한다 (현재는 폴더만 존재 또는 미존재): + +- `ops/` — 배포·모니터링·운영 knowledge +- `tasks/` — 이슈 단위 누적 knowledge +- `incidents/` — 장애 / post-mortem +``` + +**Option B — 폴더가 실제로 존재하면 비어있는 폴더 삭제 + 안내 제거.** + +폴더 존재 여부 먼저 확인: + +```bash +ls docs/wiki/wiki/ +``` + +미존재 폴더는 안내 자체를 제거(Option B), 존재한다면 Option A. + +- [ ] **Step 14.3: 프론트매터 `updated` 갱신** + +```yaml +updated: 2026-05-21 +``` + +- [ ] **Step 14.4: Commit** + +```bash +git add docs/wiki/wiki/INDEX.md +git commit -m "docs(wiki): fix INDEX.md interface/impl drift, manual maintenance explicit (#561)" +``` + +--- + +### Task 15: PR-C Draft 생성 + +- [ ] **Step 15.1: 변경 검증** + +```bash +echo "== _archive 구조 ==" +ls docs/_archive/ +echo "== warehouse-schema 참조 잔존 ==" +rg "docs/agent/warehouse-schema" --type md +echo "== INDEX.md auto-ingest 잔존 ==" +rg "Sub-3 ingest 파이프라인이 신규/갱신 파일을 자동 등재" --type md +``` + +Expected: archive에 README + warehouse-schema, 위 두 grep 0건. + +- [ ] **Step 15.2: PR-C 생성** + +```bash +gh pr create --base dev --draft \ + --title "docs(harness): archive deprecated docs + INDEX.md cleanup (#561 PR-C)" \ + --body-file <(cat <<'EOF' +## Summary + +#561 Sub-task #5 + #7 — deprecated artifact 정리 + wiki INDEX.md 인터페이스/구현 정렬. + +- [x] `docs/_archive/` 신설 + 정책 README +- [x] `docs/agent/warehouse-schema.md` → `docs/_archive/warehouse-schema.md` 이동 +- [x] `docs/agent/README.md`의 inventory에서 archived 항목 제거 +- [x] `docs/wiki/wiki/INDEX.md`의 "Sub-3 ingest 자동 등재" 문구 제거 → 수동 유지 명시 +- [x] 빈 카테고리 처리 + +## Follow-up (본 PR 범위 외) + +- `docs/qa-screenshots/` 정책 (분기별 archive 등) — 별도 이슈 +- `docs/post-centric-refactoring-summary.md` 등 archive 후보 — 검토 결과에 따라 별도 PR + +## Verification + +- `rg "docs/agent/warehouse-schema"` → 0건 +- INDEX.md auto-ingest 문구 → 0건 + +## Linked + +Closes #561 (Sub-task #5, #7). +EOF +) +``` + +--- + +## Final Verification + +세 PR이 모두 merge 후 (또는 PR-A 단독으로도) 다음 grep이 통과해야 한다: + +- [ ] **Step F.1: docs/agents/ 0건** + + ```bash + rg "docs/agents/" --type md + ``` + + Expected: 0건. + +- [ ] **Step F.2: AGENTS.md 단독 진입 가능성** + + ```bash + # Codex/Cursor/Warp 시뮬레이션 — AGENTS.md만 읽고 다음으로 갈 수 있는가? + grep -E "(ownership-matrix|docs/agent/README|docs/agent/skills|docs/wiki/wiki/harness)" AGENTS.md + ``` + + Expected: 모든 키 link 발견. + +- [ ] **Step F.3: ownership-matrix drift 0건** + + ```bash + # routing table을 복제하는 파일이 남아있지 않은지 + for f in AGENTS.md CLAUDE.md WARP.md AGENT.md; do + echo "=== $f ===" + grep -c "정본 (C)" "$f" || true + done + ``` + + Expected: 모두 0 (ownership-matrix 외에는 표 사본 없음). + +- [ ] **Step F.4: ADR vault 일원화** + + ```bash + cat docs/adr/index.md + cat docs/adr/ADR-0001-ai-dev-boilerplate.md | head -10 + ``` + + Expected: 모두 vault link 포함, monorepo 측은 stub. + +- [ ] **Step F.5: 이슈 클로즈** + +세 PR이 모두 merge되면 #561은 자동으로 close된다 (PR 본문에 `Closes part of #561` 명시). 마지막 PR(예: PR-C)에서 `Closes #561`을 사용한다. + +--- + +## Roll-back Plan + +각 PR이 독립적으로 revertable하다: + +- PR-A revert 시: 기존 7개 진입 파일 복귀, drift 다시 발생. +- PR-B revert 시: ADR monorepo 본문 복귀 (백업 `/tmp/561-adr-backup/`). +- PR-C revert 시: warehouse-schema가 `docs/agent/`로 복귀, INDEX.md auto-ingest 문구 복귀. + +vault PR(ADR-0003 작성) 실패 시 PR-B는 monorepo 측 stub만 두고 ADR-0003 row를 ownership-matrix에서 일단 제거하거나 `proposed` 상태로 둔다. From 554c9653a1604fc24756cc97fe45d3e8b4c54198 Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:06:22 +0900 Subject: [PATCH 03/10] docs(harness): expand AGENTS.md as canonical cross-tool entry (#561) --- AGENTS.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 83 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bab9ebf4..5305cef7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,85 @@ -# Agents +# AGENTS.md — Cross-tool agent entry point -This repository uses **[CLAUDE.md](CLAUDE.md)** as the short entry map (rules and links). +이 파일은 monorepo의 **canonical agent 진입점**이다. 모든 LLM 도구(Codex / Cursor / Warp / Claude Code / Gemini CLI)는 작업 시작 시 이 파일을 **가장 먼저** 읽는다. -- **Inventories** (routes, `/api/v1/*`, hooks, design system): [`docs/agent/README.md`](docs/agent/README.md) -- **Korean agent map**: [`AGENT.md`](AGENT.md) +각 도구별 overlay는 본 파일을 보강만 한다 — 본 파일과 충돌하면 본 파일이 우선한다. + +## 도구별 overlay 매핑 + +| 도구 | Overlay 파일 | 역할 | +| ----------------- | ---------------------- | --------------------------------------------------------------- | +| Claude Code | `CLAUDE.md` | Claude Code 전용 routing 규칙(skill, OMC, GSD, Superpowers) | +| Warp Terminal | `WARP.md` | Warp 워크플로우 명령·자동화 | +| Cursor | `.cursor/rules/*.mdc` | Cursor 네이티브 규칙(globs · description) | +| Codex CLI | `~/.codex/config.toml` | Hybrid harness Layer 2/2.5 (codex exec --profile fast / strict) | +| 한국어 진입(공통) | `AGENT.md` | `AGENTS.md` 1줄 redirect | + +## 읽기 우선순위 + +1. **AGENTS.md** (이 파일) — cross-tool 공통 +2. **`docs/wiki/schema/ownership-matrix.md`** — 정보 카테고리별 정본/pointer 매핑 SSOT +3. **`docs/agent/README.md`** — agent 참조 인벤토리 목차 (라우트, API, 훅, 디자인 시스템) +4. **`.planning/codebase/*`** — 스택·아키텍처·컨벤션·테스트 +5. 도구별 overlay (`CLAUDE.md`, `WARP.md`, `.cursor/rules`, ...) + +## Routing SSOT + +정보 카테고리별로 어디를 정본으로 보아야 하는지는 **`docs/wiki/schema/ownership-matrix.md`** 하나가 결정한다. 다른 파일은 그 행을 가리키기만 한다 — 표를 복제하지 않는다. + +대표 항목: + +- Stack/버전 → `.planning/codebase/STACK.md` +- 코딩 컨벤션 → `docs/wiki/schema/conventions.md` +- Skills inventory → **`docs/agent/skills.md`** +- ADR → vault `Architecture/adr/` (monorepo 측 stub: `docs/adr/index.md`) +- Harness wiki → `docs/wiki/wiki/harness/*` +- Cross-tool agent entry → 이 파일 + +전체 매트릭스: [`docs/wiki/schema/ownership-matrix.md`](docs/wiki/schema/ownership-matrix.md) + +## Documentation 위치 (decoded vs decoded-docs) + +| 종류 | 위치 | +| ----------------------------------------- | --------------------------------------------------------------------------------- | +| 코드 · LLM 라우팅 · agent 인벤토리 · spec | **이 레포** (`docs/agent/`, `docs/superpowers/`, `AGENTS.md`, 등) | +| 회의 · 결정 · 기획 · 아키텍처 · 회고 | **[decoded-docs vault](https://github.com/decodedcorp/decoded-docs)** (별도 레포) | + +전체 sync policy: [decoded-docs/Guides/sync-policy.md](https://github.com/decodedcorp/decoded-docs/blob/main/Guides/sync-policy.md) + +회사 지식 질의(예: "지난주 결정 뭐였어?")는 Telegram 매니저 agent에게 — vault 기반 답변. + +## 작업 유형별 진입 파일 + +| 작업 | 문서 | +| ------------------------------ | --------------------------------------- | +| 명령어·패키지 구조·로컬 deps | `docs/agent/monorepo.md` | +| 웹 라우트·기능 영역 | `docs/agent/web-routes-and-features.md` | +| Next.js `app/api/v1` | `docs/agent/api-v1-routes.md` | +| 훅·스토어 | `docs/agent/web-hooks-and-stores.md` | +| 디자인 시스템 import·컴포넌트 | `docs/agent/design-system-llm.md` | +| Skills · slash commands | `docs/agent/skills.md` | +| Setup (issue tracker · triage) | `docs/agent/setup/` | +| Rust API crate | `packages/api-server/AGENT.md` | +| 아키텍처·컨벤션·스택 심층 | `.planning/codebase/` | +| Harness 세션 규율 | `docs/wiki/wiki/harness/*` | + +## 반드시 지킬 것 + +1. **패키지 매니저**: **bun** (`bun run`, `bun add`). yarn/npm 아님. +2. **상세 표의 SSOT**: `docs/agent/` + `ownership-matrix.md` — overlay 파일에는 링크만. +3. **Git workflow**: `feature/*` → `dev` → `main`. `main` 직접 push 금지. 상세는 `docs/GIT-WORKFLOW.md`. +4. **Conventional Commits** 준수. +5. **Skill 라우팅**: 사용자 요청이 skill과 매치되면 Skill tool을 FIRST action으로. 직접 답하지 않는다. 상세는 `docs/agent/skills.md`. +6. **Generated 코드 금지**: `packages/web/lib/api/generated/`는 Orval 자동 생성, 수동 편집 금지. +7. **Vault 결정**: 회의·결정·아키텍처·회고는 monorepo에 두지 않는다 — 항상 vault. + +## Harness Workflow + +| Tool | Role | When | +| ----------- | -------------------- | ------------------- | +| gstack | 기획/리뷰/QA/배포 | Think → Plan → Ship | +| Superpowers | TDD, 코드 품질 강제 | Build (구현) | +| OMC | Claude + Gemini 듀얼 | 대규모 작업 보조 | +| GSD quick | 원자적 단발 패치 | 유지보수 | + + From 455b688f671b06d28aa5a7942af96dfa6c05f8f1 Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:08:34 +0900 Subject: [PATCH 04/10] docs(harness): shrink CLAUDE.md to Claude Code overlay (#561) --- CLAUDE.md | 247 +++++++----------------------------------------------- 1 file changed, 31 insertions(+), 216 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3c371714..b8babc78 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,240 +1,55 @@ -# decoded-monorepo Development Guidelines +# CLAUDE.md — Claude Code overlay -짧은 **맵**입니다. 라우트/API/훅/디자인 시스템 **표·인벤토리**는 [`docs/agent/`](docs/agent/)에 두었습니다. 해당 작업을 할 때는 항상 해당 파일을 연 뒤 진행합니다. +> 본 파일은 **Claude Code 전용 overlay**다. 공통 cross-tool 진입 규칙은 **`AGENTS.md`를 먼저 읽고**, 본 파일은 Claude Code-specific 보강만 담는다. -## Documentation 위치 (decoded vs decoded-docs) +## Read order -| 종류 | 위치 | -| ----------------------------------------- | --------------------------------------------------------------------------------- | -| 코드 · LLM 라우팅 · agent 인벤토리 · spec | **이 레포** (`docs/agent/`, `docs/superpowers/`, `CLAUDE.md`, 등) | -| 회의 · 결정 · 기획 · 아키텍처 · 회고 | **[decoded-docs vault](https://github.com/decodedcorp/decoded-docs)** (별도 레포) | +1. `AGENTS.md` (canonical, cross-tool) +2. `docs/wiki/schema/ownership-matrix.md` (routing SSOT) +3. 본 파일 (Claude Code overlay) +4. `docs/agent/README.md` (참조 인벤토리) -전체 sync policy: [decoded-docs/Guides/sync-policy.md](https://github.com/decodedcorp/decoded-docs/blob/main/Guides/sync-policy.md) +## Documentation 위치 -회사 지식 질의 (예: "지난주 결정 뭐였어?", "에디토리얼 매거진 방향성") 는 Telegram의 매니저 agent 에게 물어보면 vault 기반으로 답변합니다. +코드/LLM 라우팅/agent 인벤토리/spec은 monorepo. 회의/결정/아키텍처/회고는 vault — 자세한 사항은 `AGENTS.md` 참조. -## Overview +## Skill routing (Claude Code) -Monorepo for the decoded platform — image/item discovery and curation with behavioral intelligence, editorial magazine system (news-referenced), virtual try-on (VTON), admin dashboard (seed pipeline, entity management, monitoring), SEO infrastructure, and design system (v2.0). AI-powered item detection (Ollama vision auto-tagging), social actions (like/save/comment/follow), personalization, rankings, collection/studio. +사용자 요청이 가용 skill과 매치되면 Skill tool을 **FIRST action**으로 호출한다. 표/세부 매핑은 **`docs/agent/skills.md`**가 정본. -## Monorepo (summary) +핵심 라우팅 키워드: -- **Root**: bun workspaces + Turborepo (`package.json`, `turbo.json`, `bunfig.toml`) -- **`packages/web`**: Next.js 16 app (main frontend) -- **`packages/shared`**: Shared types, hooks, Supabase queries -- **`packages/mobile`**: Expo app -- **`packages/api-server`**: Rust/Axum (Cargo; not a bun workspace member) -- **`packages/ai-server`**: Python AI / gRPC (`uv`) +- "is this worth building" / brainstorming → `office-hours` +- bug / 500 → `investigate` +- ship / deploy / PR → `ship` +- QA → `qa` +- code review → `review` +- design system → `design-consultation` +- save progress → `checkpoint` -**상세 트리·명령어·로컬 deps·포트**: [`docs/agent/monorepo.md`](docs/agent/monorepo.md) -**기술 스택·버전**: [`.planning/codebase/STACK.md`](.planning/codebase/STACK.md) +## Commit discipline (Claude Code) -## Agent reference (`docs/agent/`) +- 작업 완료 시 검증 후 관련 파일만 선별해 커밋. 커밋 금지는 push/merge/PR 병합 금지와 구분 — 로컬 커밋은 기본 완료 조건. +- 더러운 워크트리에서는 unrelated 변경 건드리지 말고 `git add `만. +- review-only / plan-only 모드, human checkpoint 필요 작업이면 커밋하지 않고 이유 남김. -### Topic routing (1순위: `*-summary.md` → canonical) +## Worktree -Topic 질의(아키텍처 / API / DB / 디자인 시스템 / AI playbook)는 **먼저 summary**를 읽고, summary가 가리키는 canonical(`.planning/codebase/*`, `docs/architecture/`, `docs/api/`, `docs/database/`, `docs/ai-playbook/`) 으로 내려간다. canonical을 먼저 열면 설계 의도와 스냅샷을 혼동한다. +세션 격리는 `superpowers:using-git-worktrees` 사용. `.claude/worktrees/`는 `.gitignore`됨. -| Topic | Summary (먼저 읽기) | -| ------------- | ---------------------------------------------------------------------------- | -| architecture | [`docs/agent/architecture-summary.md`](docs/agent/architecture-summary.md) | -| api | [`docs/agent/api-summary.md`](docs/agent/api-summary.md) | -| database | [`docs/agent/database-summary.md`](docs/agent/database-summary.md) | -| design-system | [`docs/agent/design-system-summary.md`](docs/agent/design-system-summary.md) | -| ai-playbook | [`docs/agent/ai-playbook-summary.md`](docs/agent/ai-playbook-summary.md) | - -### 참조 인벤토리 (표·라우트·훅) - -| 문서 | 용도 | -| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| [`docs/agent/README.md`](docs/agent/README.md) | 목차·언제 무엇을 읽을지 | -| [`docs/database/operating-model.md`](docs/database/operating-model.md) | **DB 운영 모델 단일 진입점** — 영역/시스템 매트릭스, "어디 추가하나" 결정 트리, drift 회피 | -| [`docs/agent/environments.md`](docs/agent/environments.md) | **env matrix (dev=local / prod=Cloud Supabase)** | -| [`docs/DATABASE-MIGRATIONS.md`](docs/DATABASE-MIGRATIONS.md) | **DB 마이그레이션 SOT / 워크플로우** | -| [`docs/agent/staging.md`](docs/agent/staging.md) | staging 정의 (현재 없음) | -| [`docs/agent/web-routes-and-features.md`](docs/agent/web-routes-and-features.md) | 웹 라우트·기능 영역 | -| [`docs/agent/api-v1-routes.md`](docs/agent/api-v1-routes.md) | Next.js `/api/v1/*` 표 | -| [`docs/agent/web-hooks-and-stores.md`](docs/agent/web-hooks-and-stores.md) | 훅·스토어·주요 경로 | -| [`docs/agent/design-system-llm.md`](docs/agent/design-system-llm.md) | 디자인 시스템 import·컴포넌트 목록 | -| [`docs/architecture/assets-project.md`](docs/architecture/assets-project.md) | **assets Supabase 프로젝트 (#333)** — 파이프라인 스테이징 + verify 플로우 | -| [`docs/agent/verify-flow-qa.md`](docs/agent/verify-flow-qa.md) | verify 엔드포인트 수동 QA 체크리스트 | -| [`docs/agent/version-harness.md`](docs/agent/version-harness.md) | **Backend 버전 lockstep harness** — PR `bump:*` 라벨 + main 머지 시 자동 bump/tag | -| [`docs/agent/warehouse-schema.md`](docs/agent/warehouse-schema.md) | (DEPRECATED, #333) historical warehouse 스키마 reference | -| [`packages/api-server/AGENT.md`](packages/api-server/AGENT.md) | Rust API 크레이트 전용 | - -### Harness knowledge (세션 규율) - -- [`docs/wiki/wiki/harness/claude-code.md`](docs/wiki/wiki/harness/claude-code.md) — Claude Code 세션·worktree·Draft PR·Auto Mode -- [`docs/wiki/wiki/harness/session-discipline.md`](docs/wiki/wiki/harness/session-discipline.md) — 세션 분리, 상태 격리, cwd 리셋 -- [`docs/wiki/wiki/harness/commit-protocol.md`](docs/wiki/wiki/harness/commit-protocol.md) — Conventional Commits, fmt/check, PR 범위 -- [`docs/wiki/wiki/harness/review-flow.md`](docs/wiki/wiki/harness/review-flow.md) — 리뷰/검증 레인 분리, self-approve 금지 - -## Conventions (SSOT) - -상세 컨벤션은 [docs/wiki/schema/conventions.md](docs/wiki/schema/conventions.md)를 참조한다. 이 파일은 agent routing과 docs 맵만 담는다. - -주요 규칙 요약: - -- bun + Turborepo -- Conventional Commits -- Next.js 16은 `proxy.ts` 사용 -- `packages/web/lib/api/generated/`는 자동 생성, 수동 편집 금지 - -## Git workflow - -요약: `feature/*` → `dev` → `main` 플로우. `main` 직접 push 금지, `dev`→`main` PR 머지만 허용. 긴급 시 `hotfix/*`→`main` 예외. 상세는 **[docs/GIT-WORKFLOW.md](docs/GIT-WORKFLOW.md)**. - -## Commit discipline - -- 사용자가 코드/문서 수정을 요청하고 작업이 완료되면, 검증 후 관련 파일만 선별해 커밋한다. -- 커밋 금지는 `push`, `merge`, PR 병합 금지와 구분한다. 로컬 커밋은 기본 완료 조건이다. -- 더러운 워크트리에서는 unrelated 변경을 건드리지 말고, 이번 작업 파일만 `git add `로 스테이징한다. -- 커밋하지 않아야 하는 명시 요청, review-only/plan-only 모드, 또는 human checkpoint가 필요한 위험 작업이면 커밋하지 않고 이유를 남긴다. - -## Codebase documentation - -| 문서 | 내용 | -| ----------------------------------------------------- | ----------------------------- | -| [STACK.md](.planning/codebase/STACK.md) | 기술 스택, 의존성, 설정 | -| [ARCHITECTURE.md](.planning/codebase/ARCHITECTURE.md) | 아키텍처, 레이어, 데이터 흐름 | -| [STRUCTURE.md](.planning/codebase/STRUCTURE.md) | 디렉토리 구조 | -| [CONVENTIONS.md](.planning/codebase/CONVENTIONS.md) | 코딩 컨벤션 | -| [TESTING.md](.planning/codebase/TESTING.md) | 테스트 | -| [INTEGRATIONS.md](.planning/codebase/INTEGRATIONS.md) | 외부 연동 | -| [CONCERNS.md](.planning/codebase/CONCERNS.md) | 기술 부채 | - -## GSD Workflow +## GSD Workflow (quick reference) ```bash +/gsd:quick # 빠른 작업 /gsd:progress # 전체 진행 상황 -/gsd:discuss-phase N # 페이즈 N 논의 -/gsd:plan-phase N # 페이즈 N 계획 -/gsd:execute-phase N # 페이즈 N 실행 -/gsd:verify-work # 작업 검증 /gsd:help # 명령어 목록 -/gsd:quick # 빠른 작업 ``` -## Harness Workflow - -| Tool | Role | When | -| ----------- | -------------------- | ------------------- | -| gstack | 기획/리뷰/QA/배포 | Think → Plan → Ship | -| Superpowers | TDD, 코드 품질 강제 | Build (구현) | -| OMC | Claude + Gemini 듀얼 | 대규모 작업 보조 | -| GSD quick | 원자적 단발 패치 | 유지보수 | - -## Documentation - -- [docs/README.md](docs/README.md) — 문서 인덱스 -- [docs/GIT-WORKFLOW.md](docs/GIT-WORKFLOW.md) — 브랜치, 커밋, PR -- [docs/agent/](docs/agent/) — 에이전트용 참조 (표·인벤토리) -- [docs/design-system/](docs/design-system/) — 디자인 토큰 -- [.planning/](.planning/) — GSD 아티팩트 -- docs/adr/, docs/api/, docs/ai-playbook/ - -## gstack (Software Factory) - -Use gstack slash commands for the sprint workflow: **Think → Plan → Build → Review → Test → Ship → Reflect**. - -### Available Skills - -| Phase | Command | Role | -| ------- | -------------------------------------------- | ----------------------------------------- | -| Think | `/office-hours` | YC Office Hours — reframe the product | -| Plan | `/plan-ceo-review` | CEO — rethink scope | -| Plan | `/plan-eng-review` | Eng Manager — lock architecture | -| Plan | `/plan-design-review` | Designer — rate & improve design | -| Plan | `/design-consultation` | Design Partner — build design system | -| Plan | `/autoplan` | Auto-review pipeline: CEO → design → eng | -| Build | `/browse` | Browser automation (Playwright) | -| Review | `/review` | Staff Engineer — find production bugs | -| Review | `/design-review` | Designer Who Codes — audit + fix | -| Review | `/cso` | Security Officer — OWASP + STRIDE audit | -| Test | `/qa` | QA Lead — real browser testing + auto-fix | -| Test | `/qa-only` | QA report only (no fixes) | -| Ship | `/ship` | Release Engineer — test, PR, ship | -| Ship | `/land-and-deploy` | Merge → deploy → canary verify | -| Monitor | `/canary` | Post-deploy monitoring | -| Monitor | `/benchmark` | Performance regression detection | -| Debug | `/investigate` | Systematic root-cause debugging | -| Reflect | `/retro` | Sprint retrospective | -| Docs | `/document-release` | Post-ship doc updates | -| Safety | `/careful`, `/freeze`, `/guard`, `/unfreeze` | Destructive op protection | -| Setup | `/setup-deploy`, `/setup-browser-cookies` | One-time config | -| Utility | `/gstack-upgrade` | Update gstack | -| Utility | `/codex` | Multi-AI second opinion | -| Utility | `/connect-chrome` | Connect Chrome for browsing | - -### Rules - -- Use `/browse` for all web browsing — never use `mcp__claude-in-chrome__*` tools -- If gstack skills aren't working, run `cd ~/.claude/skills/gstack && ./setup` -- Follow the sprint order: Think → Plan → Build → Review → Test → Ship → Reflect - - - -## Agent skills - -### Issue tracker - -GitHub Issues at [decodedcorp/decoded](https://github.com/decodedcorp/decoded), `gh` CLI. See [`docs/agents/issue-tracker.md`](docs/agents/issue-tracker.md). - -### Triage labels - -Canonical 5-role mapping (`needs-triage`/`needs-info`/`ready-for-agent`/`ready-for-human`/`wontfix`). See [`docs/agents/triage-labels.md`](docs/agents/triage-labels.md). - -### Domain docs - -Multi-context (monorepo). Entry: `CLAUDE.md` + `.planning/codebase/*`. ADRs in `docs/adr/`. See [`docs/agents/domain.md`](docs/agents/domain.md). - -## Skill routing - -When the user's request matches an available skill, ALWAYS invoke it using the Skill -tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. -The skill has specialized workflows that produce better results than ad-hoc answers. - -Key routing rules: - -- Product ideas, "is this worth building", brainstorming → invoke office-hours -- Bugs, errors, "why is this broken", 500 errors → invoke investigate -- Ship, deploy, push, create PR → invoke ship -- QA, test the site, find bugs → invoke qa -- Code review, check my diff → invoke review -- Update docs after shipping → invoke document-release -- Weekly retro → invoke retro -- Design system, brand → invoke design-consultation -- Visual audit, design polish → invoke design-review -- Architecture review → invoke plan-eng-review -- Save progress, checkpoint, resume → invoke checkpoint -- Code quality, health check → invoke health - -### Spec/Generator skills (audit #558) - -| Trigger 키워드 | Skill | -| --------------------------------------------------------- | ---------------------------- | -| "screen spec", "화면 명세", "document screen" | screen-spec-generator | -| "data model", "generate types", "create interface" | data-model-generator | -| "API contract", "OpenAPI", "endpoint spec" | api-contract-generator | -| "scaffold component", "create component", "컴포넌트 생성" | component-template-generator | -| "migration", "database schema", "테이블 생성" | supabase-migration-generator | -| "excalidraw", "다이어그램", "flowchart", "ERD" | excalidraw-generator | -| "pencil ui", "screen ui", "디자인 구현", "UI 구현" | pencil-screen-ui | -| "meeting prep", "weekly update", "주간 보고" | meeting-prep | -| "브랜치 이름", "commit convention", "PR 준비" | git-workflow | - -### Matt Pocock slash commands (audit #558) - -| Command | 용도 | -| -------------------- | ------------------------------------------------------------------------------------------- | -| `/grill` | plan/design을 인터뷰로 결정 분기 풀기 | -| `/grill-docs` | plan을 도메인 모델·ADR과 함께 grill | -| `/to-prd` | 대화 맥락을 PRD로 응축해 issue tracker에 publish | -| `/to-issues` | plan/PRD를 vertical slice GitHub Issues로 분해 | -| `/zoom-out` | 현재 코드/맥락을 더 넓은 시야로 다시 보기 | -| `/setup-matt-skills` | issue tracker / triage labels / domain docs 위치를 AGENTS.md·CLAUDE.md에 등록 (1회성 setup) | +자세한 GSD/gstack/Superpowers 경계는 `AGENTS.md`의 Harness Workflow 표 참조. + + -- [Antigravity Rules](file:///Users/kiyeol/development/decoded/decoded-app/.antigravity/rules.md) - Autonomous execution policy and language preferences. +- [Antigravity Rules](file:///Users/kiyeol/development/decoded/decoded-app/.antigravity/rules.md) — Autonomous execution policy and language preferences. From 08504487ceb9b6abb3ef65f7f5c7056bab2972a1 Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:10:47 +0900 Subject: [PATCH 05/10] docs(harness): align WARP.md as Warp overlay, defer common rules to AGENTS.md (#561) --- WARP.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) mode change 120000 => 100644 WARP.md diff --git a/WARP.md b/WARP.md deleted file mode 120000 index 681311eb..00000000 --- a/WARP.md +++ /dev/null @@ -1 +0,0 @@ -CLAUDE.md \ No newline at end of file diff --git a/WARP.md b/WARP.md new file mode 100644 index 00000000..3d920002 --- /dev/null +++ b/WARP.md @@ -0,0 +1,42 @@ +# WARP.md — Warp Terminal overlay + +> 본 파일은 **Warp Terminal 전용 overlay**다. 공통 cross-tool 진입 규칙은 **`AGENTS.md`를 먼저 읽고**, 본 파일은 Warp-specific 보강(워크플로우 명령·자동화)만 담는다. +> +> Read order: `AGENTS.md` → `docs/wiki/schema/ownership-matrix.md` → 본 파일. + +## Documentation 위치 + +→ `AGENTS.md` 참조. + +## Harness Workflow + +→ `AGENTS.md` 참조. + +## Skill routing + +→ `AGENTS.md` + `docs/agent/skills.md` 참조. + +## Warp-specific 보강 + +Warp Terminal에서 본 monorepo를 운영할 때만 적용되는 가이드. + +### Workflow 명령 (Warp Workflows) + +Warp의 [Workflows](https://docs.warp.dev/features/workflows) 기능으로 자주 쓰는 monorepo 명령을 등록해 두면 효율적이다. + +| Workflow 이름 | 명령 | 용도 | +| ------------------ | ------------------------ | ------------------------ | +| `decoded:dev` | `bun run dev` | 로컬 dev 서버 기동 | +| `decoded:gen-api` | `bun run generate:api` | Orval+Zod 타입 재생성 | +| `decoded:db-types` | `bun run gen:types` | Supabase types.ts 재생성 | +| `decoded:turbo` | `bun run build` | Turborepo 빌드 | +| `decoded:wiki` | `/oh-my-claudecode:wiki` | LLM Wiki 진입 | + +### Terminal automation tip + +- Warp의 AI Command 검색은 `#` 트리거로 호출. monorepo 컨벤션상 `bun`/`turbo`/`cargo`/`uv` 4종이 자주 등장하므로 별칭 등록 권장. +- `git worktree` 사용 시 Warp 탭별로 다른 worktree를 띄우면 세션 격리에 유리하다. 세션 규율은 `docs/wiki/wiki/harness/session-discipline.md` 참조. + +### 자동화 스크립트 + +monorepo 루트의 `scripts/`에 정의된 자동화는 Warp Workflows로 wrap해도 무방하다. 단, 위험 작업(DB 변경, 대량 삭제)은 워크플로우로 등록해도 confirmation prompt를 유지할 것. From 0b6c59a208e3f712d6403aa08b3c901b885203b6 Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:12:52 +0900 Subject: [PATCH 06/10] docs(harness): point .cursor/rules to AGENTS.md as common entry (#561) --- .cursor/rules/api-routes.mdc | 2 ++ .cursor/rules/monorepo.mdc | 2 ++ .cursor/rules/react-components.mdc | 2 ++ .cursor/rules/rust-api.mdc | 2 ++ 4 files changed, 8 insertions(+) diff --git a/.cursor/rules/api-routes.mdc b/.cursor/rules/api-routes.mdc index 476935ad..b1e0922e 100644 --- a/.cursor/rules/api-routes.mdc +++ b/.cursor/rules/api-routes.mdc @@ -3,6 +3,8 @@ description: Next.js API route conventions globs: "packages/web/app/api/**/*.ts" --- +> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지. + # API Route Conventions ## Handler Format diff --git a/.cursor/rules/monorepo.mdc b/.cursor/rules/monorepo.mdc index b9f69f99..3e377382 100644 --- a/.cursor/rules/monorepo.mdc +++ b/.cursor/rules/monorepo.mdc @@ -3,6 +3,8 @@ description: decoded-monorepo conventions and architecture globs: "**/*" --- +> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지. + # decoded-monorepo ## Structure diff --git a/.cursor/rules/react-components.mdc b/.cursor/rules/react-components.mdc index e54855e0..36838936 100644 --- a/.cursor/rules/react-components.mdc +++ b/.cursor/rules/react-components.mdc @@ -3,6 +3,8 @@ description: React component conventions for decoded web package globs: "packages/web/**/*.tsx" --- +> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지. + # React Component Conventions ## Server vs Client Components diff --git a/.cursor/rules/rust-api.mdc b/.cursor/rules/rust-api.mdc index 29565913..68d13f96 100644 --- a/.cursor/rules/rust-api.mdc +++ b/.cursor/rules/rust-api.mdc @@ -3,6 +3,8 @@ description: Rust API server conventions (Axum + SeaORM) globs: "packages/api-server/**/*.rs" --- +> Cross-tool 공통 진입 규칙은 [`AGENTS.md`](mdc:AGENTS.md)를 먼저 읽는다. 본 파일은 Cursor 네이티브 규칙(globs · description)과 repo 특이사항만 유지. + # Rust API Server Conventions ## Stack From 9f7aebb430a6f4970f3484980bae5741cf174f0c Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:14:40 +0900 Subject: [PATCH 07/10] docs(harness): redirect AGENT.md to AGENTS.md (#561) --- AGENT.md | 38 +++----------------------------------- 1 file changed, 3 insertions(+), 35 deletions(-) diff --git a/AGENT.md b/AGENT.md index 97f969e3..5c40c3d5 100644 --- a/AGENT.md +++ b/AGENT.md @@ -1,37 +1,5 @@ -# decoded-app AI 에이전트 맵 +# AGENT.md — 한국어 진입점 (redirect) -> **Purpose**: AI 에이전트가 이 모노레포에서 작업할 때의 **한국어 진입점**입니다. 장문·표는 [`docs/agent/`](docs/agent/)와 [`.planning/codebase/`](.planning/codebase/)에 두었습니다. +본 파일은 `AGENTS.md`로 합쳐졌다. 한국어 작업 메모를 포함한 cross-tool 진입 규칙은 **[`AGENTS.md`](AGENTS.md)** 를 읽는다. -## 필수 진입 문서 - -| 문서 | 역할 | -|------|------| -| **[CLAUDE.md](CLAUDE.md)** | 영문 **맵** (항상 읽기 쉬운 요약, 규칙, `docs/agent` 인덱스) | -| **[docs/agent/README.md](docs/agent/README.md)** | 표·인벤토리 목차 (라우트, API, 훅, 디자인 시스템) | -| **[.planning/codebase/](.planning/codebase/)** | 아키텍처, 스택, 컨벤션, 테스트, 연동 | - -## 작업 유형별로 열 파일 - -| 작업 | 문서 | -|------|------| -| 명령어·패키지 구조·로컬 deps | [docs/agent/monorepo.md](docs/agent/monorepo.md) | -| 웹 라우트·기능 영역 | [docs/agent/web-routes-and-features.md](docs/agent/web-routes-and-features.md) | -| Next.js `app/api/v1` | [docs/agent/api-v1-routes.md](docs/agent/api-v1-routes.md) | -| 훅·스토어·주요 경로 | [docs/agent/web-hooks-and-stores.md](docs/agent/web-hooks-and-stores.md) | -| 디자인 시스템 import·컴포넌트 목록 | [docs/agent/design-system-llm.md](docs/agent/design-system-llm.md) | -| Warehouse 스키마 (ETL·Seed) | [docs/agent/warehouse-schema.md](docs/agent/warehouse-schema.md) | -| Rust API 서버 (`api-server`) | [packages/api-server/AGENT.md](packages/api-server/AGENT.md) | - -## 반드시 지킬 것 - -1. **패키지 매니저**: **bun** (`bun run`, `bun add`). yarn/npm 아님. -2. **상세 표의 SSOT**: `docs/agent/` — CLAUDE.md에는 링크만 있음. -3. **디자인 시스템**: 새 UI는 [docs/design-system/](docs/design-system/) 및 `docs/agent/design-system-llm.md` 확인. -4. **Supabase 쿼리**: 웹은 `packages/web/lib/supabase/queries/` 패턴 유지. - -## 기타 - -- 디자인 시스템 토큰·UI 가이드: [docs/design-system/README.md](docs/design-system/README.md) -- 문서 인덱스: [docs/README.md](docs/README.md) - -**마지막 업데이트**: 2026-04-02 +(파일 자체는 외부 link 호환을 위해 유지.) From 354f3213813d5ed6d203f6e8c11b43b3dbd01333 Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:16:41 +0900 Subject: [PATCH 08/10] docs(harness): promote ownership-matrix to routing SSOT, add 5 new rows (#561) --- docs/wiki/schema/ownership-matrix.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/wiki/schema/ownership-matrix.md b/docs/wiki/schema/ownership-matrix.md index dd25a2cd..5b6205c9 100644 --- a/docs/wiki/schema/ownership-matrix.md +++ b/docs/wiki/schema/ownership-matrix.md @@ -2,7 +2,7 @@ title: Ownership Matrix owner: human status: approved -updated: 2026-04-17 +updated: 2026-05-21 tags: [harness, agent] related: - docs/wiki/schema/frontmatter.md @@ -32,6 +32,11 @@ related: | 하네스 규칙 (gstack·Superpowers·OMC·GSD 경계) | `docs/wiki/schema/harness.md` | `CLAUDE.md`, `.cursor/rules` | | Git workflow | `docs/GIT-WORKFLOW.md` | `CLAUDE.md` | | React/API/Rust 코드 패턴 | `.cursor/rules/{react-components,api-routes,rust-api}.mdc` | `docs/wiki/schema/conventions.md` (요약 링크) | +| ADR (Architectural Decisions) | vault `Architecture/adr/` | `docs/adr/index.md` | +| Harness wiki (세션 규율) | `docs/wiki/wiki/harness/*` | `AGENTS.md`, `docs/agent/README.md` | +| Skills inventory (gstack/Matt/Spec) | `docs/agent/skills.md` | `AGENTS.md`, `CLAUDE.md`, `WARP.md` | +| Cross-tool agent entry (도구별 overlay 매핑) | `AGENTS.md` | `CLAUDE.md`, `WARP.md`, `.cursor/rules/*.mdc`, `AGENT.md` | +| Vault contract (3-repo ecosystem) | vault `Guides/sync-policy.md` + ADR-0003 | `docs/wiki/schema/ownership-matrix.md` (본 파일) | ## 원칙 @@ -39,3 +44,5 @@ related: 2. Pointer 파일은 2~5줄 요약 + "Canonical: <경로>" 라인만 가진다. 3. `docs/agent/` 내 기존 substantive 파일(`warehouse-schema.md`, `api-v1-routes.md`, `web-hooks-and-stores.md`)은 정본으로 승격된다. 4. Sub-3 linter가 카테고리별 정본 참조 일관성을 검증한다. +5. **ADR canonical은 vault**. monorepo `docs/adr/`는 redirect index만 유지한다. 자세한 결정은 ADR-0003 참조. +6. **Cross-tool entry**의 정본은 `AGENTS.md`. Claude/Warp/Cursor overlay는 본 파일을 가리킨다. From f77fd0462e6d03cf1c6aabe89cdb22913b8ce701 Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:18:24 +0900 Subject: [PATCH 09/10] docs(harness): merge docs/agents/ into docs/agent/setup/ (#561) --- docs/agent/README.md | 11 ++++++++++- docs/{agents => agent/setup}/domain.md | 0 docs/{agents => agent/setup}/issue-tracker.md | 0 docs/{agents => agent/setup}/triage-labels.md | 0 4 files changed, 10 insertions(+), 1 deletion(-) rename docs/{agents => agent/setup}/domain.md (100%) rename docs/{agents => agent/setup}/issue-tracker.md (100%) rename docs/{agents => agent/setup}/triage-labels.md (100%) diff --git a/docs/agent/README.md b/docs/agent/README.md index d0533857..fabe8eb3 100644 --- a/docs/agent/README.md +++ b/docs/agent/README.md @@ -2,7 +2,7 @@ title: Agent reference (`docs/agent/`) owner: human status: approved -updated: 2026-04-21 +updated: 2026-05-21 tags: [agent, harness] --- @@ -37,6 +37,15 @@ tags: [agent, harness] | 아키텍처·컨벤션·스택 심층 | [`.planning/codebase/`](../../.planning/codebase/) | | 디자인 토큰·UI 상세 | [`docs/design-system/`](../design-system/) | +## Setup (1회성) + +| 항목 | 문서 | +| ---------------- | ------------------------------------------------ | +| Issue tracker | [setup/issue-tracker.md](setup/issue-tracker.md) | +| Triage labels | [setup/triage-labels.md](setup/triage-labels.md) | +| Domain docs 위치 | [setup/domain.md](setup/domain.md) | +| Skills inventory | [skills.md](skills.md) | + ## Rust API crate `packages/api-server` 전용 가이드는 [`packages/api-server/AGENT.md`](../../packages/api-server/AGENT.md)를 사용합니다. diff --git a/docs/agents/domain.md b/docs/agent/setup/domain.md similarity index 100% rename from docs/agents/domain.md rename to docs/agent/setup/domain.md diff --git a/docs/agents/issue-tracker.md b/docs/agent/setup/issue-tracker.md similarity index 100% rename from docs/agents/issue-tracker.md rename to docs/agent/setup/issue-tracker.md diff --git a/docs/agents/triage-labels.md b/docs/agent/setup/triage-labels.md similarity index 100% rename from docs/agents/triage-labels.md rename to docs/agent/setup/triage-labels.md From 56b5e9737b55f733fce2e21d410070e2408a00ca Mon Sep 17 00:00:00 2001 From: thxforall <113906780+thxforall@users.noreply.github.com> Date: Thu, 21 May 2026 19:41:23 +0900 Subject: [PATCH 10/10] docs(wiki): add `skills` tag to vocabulary for docs/agent/skills.md (#561) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/agent/skills.md` introduced in this PR uses `tags: [agent, harness, skills]` but `skills` was missing from the vocab, breaking wiki-lint. Add `skills` to the domain category — slash command / skill 카탈로그 의미. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/wiki/schema/tags.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/wiki/schema/tags.md b/docs/wiki/schema/tags.md index df9e42fb..2fe24b1c 100644 --- a/docs/wiki/schema/tags.md +++ b/docs/wiki/schema/tags.md @@ -2,7 +2,7 @@ title: Tag Vocabulary owner: human status: approved -updated: 2026-04-17 +updated: 2026-05-21 tags: [harness, agent] related: - docs/wiki/schema/frontmatter.md @@ -24,6 +24,7 @@ related: | `testing` | 단위·통합·E2E 테스트 | | `ops` | 배포, 모니터링, 운영 | | `security` | 인증, RLS, 권한 | +| `skills` | slash command / skill 카탈로그 | ## 역할 (role)