forgedev 1.1.0 → 1.2.0

package/docs/02-claude-code-mastery-playbook.md

@@ -0,0 +1,283 @@
+# Claude Code Mastery Playbook
+## How to Structure Your Project for Production-Grade AI-Assisted Development
+
+---
+
+## The Core Problem
+
+Your CLAUDE.md is too long and tries to do too much. Research shows Claude Code
+reliably follows about 150 instructions — its own system prompt uses ~50, leaving
+you ~100-150 for your project rules. If your CLAUDE.md exceeds that, instructions
+get dropped uniformly.
+
+The fix: move enforcement to hooks (deterministic), domain knowledge to skills
+(on-demand), and keep CLAUDE.md lean (~150 lines of universally-applicable rules).
+
+---
+
+## Part 1: Lean CLAUDE.md (~150 Lines)
+
+### Structure: WHAT → WHY → HOW → RULES
+
+```markdown
+# [Your Project Name]
+
+## WHAT (Project Map)
+- [Tech stack: e.g., React 19 + TypeScript + FastAPI + PostgreSQL]
+- /src — frontend source
+- /backend — API and business logic
+- /e2e — end-to-end tests
+- [List key directories and what they contain]
+
+## WHY (Purpose)
+- [One sentence: what the product does and who it's for]
+- [Key architectural decisions worth knowing]
+
+## HOW (Verification Commands)
+- Lint: [your lint command]
+- Type check: [your type check command]
+- Unit tests: [your test command]
+- E2E tests: [your e2e command]
+- Build: [your build command]
+
+## RULES (Only What the Agent Gets Wrong)
+- [IMPORTANT: Rule that prevents a recurring mistake]
+- [IMPORTANT: Another rule that prevents a recurring mistake]
+- [Pattern to follow consistently]
+- [Pattern to follow consistently]
+
+## Known Pitfalls (Recurring Bugs)
+- [Bug pattern 1: what happens and how to avoid it]
+- [Bug pattern 2: what happens and how to avoid it]
+
+## Build Order
+[your project's dependency order, e.g.:]
+models → backend logic → API endpoints → frontend API client → components → pages
+
+## Completion Protocol
+Before reporting ANY task as done:
+1. Re-read the original instruction word-by-word
+2. Run all verification commands
+3. Trace every new wire: source → transport → consumer → render
+4. Show proof: file paths, what connects to what
+```
+
+### What NOT to Put in CLAUDE.md
+
+- Data model schemas → move to a Skill
+- Full API endpoint inventories → move to a Skill
+- Detailed security checklists → move to a Skill
+- Framework-specific patterns → move to directory-scoped CLAUDE.md
+- Anything only relevant to one module → move to a Skill
+- Anything that MUST happen every time → move to a Hook
+
+---
+
+## Part 2: Skills (On-Demand Knowledge)
+
+Skills load only when Claude works on relevant files. Unlike CLAUDE.md
+(loaded every session), skills don't waste context on irrelevant information.
+
+### Creating a Skill
+
+```
+.claude/skills/
+  [skill-name]/
+    SKILL.md
+```
+
+### Example Skill Structure
+
+```markdown
+---
+name: [skill-name]
+description: [When Claude should load this skill — be specific]
+---
+
+# [Skill Title]
+
+## [Section 1: Patterns]
+[Patterns, conventions, and examples specific to this domain]
+
+## [Section 2: Anti-Patterns]
+[What NOT to do]
+
+## [Section 3: Examples]
+[Reference files or code examples]
+```
+
+### Common Skills to Create
+
+| Skill | Description | Contains |
+|-------|-------------|----------|
+| `testing` | Testing patterns for your framework | Locator strategy, fixtures, anti-flakiness rules |
+| `frontend` | Frontend component patterns | File structure, state management, API integration |
+| `backend` | Backend service patterns | Endpoint templates, ORM patterns, validation |
+| `security` | Full security checklist | Auth, input validation, output safety, secrets |
+| `data-models` | Schema definitions | Entity definitions, relationships, migration patterns |
+| `ai-integration` | AI/LLM prompt patterns | Prompt quality standards, output parsing, fallbacks |
+| `[domain]` | Domain-specific knowledge | Business rules, terminology, workflow logic |
+
+---
+
+## Part 3: Directory-Scoped CLAUDE.md Files
+
+Claude loads the nearest CLAUDE.md when working in a directory.
+
+```
+CLAUDE.md                  # Root: universal rules (~150 lines)
+backend/CLAUDE.md          # Backend: language + framework rules
+src/CLAUDE.md              # Frontend: UI + component rules
+e2e/CLAUDE.md              # Tests: testing rules and patterns
+```
+
+---
+
+## Part 4: Hooks (Deterministic Enforcement)
+
+See `multi-agent-verification.md` for the complete hook setup.
+
+**Three essential hooks:**
+1. **PostToolUse** — auto-lint after every file edit
+2. **Stop** — run validation before marking done (exit 2 to block)
+3. **PreToolUse** — protect files that should never be modified
+
+---
+
+## Part 5: Validating Existing Work
+
+### Audit Commands (`.claude/commands/`)
+
+| Command | File | Purpose |
+|---------|------|---------|
+| `/project:audit-spec` | `audit-spec.md` | Check implementation vs specification |
+| `/project:audit-wiring` | `audit-wiring.md` | Find dead endpoints, methods, components |
+| `/project:pre-pr` | `pre-pr.md` | Full validation before creating PR |
+| `/project:audit-prompts` | `audit-prompts.md` | Score AI prompts (if applicable) |
+| `/project:run-uat` | `run-uat.md` | Execute UAT scenarios, report coverage |
+| `/project:audit-resilience` | `audit-resilience.md` | Check failover, health, graceful shutdown |
+| `/project:pre-deploy` | `pre-deploy.md` | Staging/pre-production smoke test |
+
+---
+
+## Part 6: UAT (User Acceptance Testing)
+
+### Every Feature Needs a UAT Scenario
+
+Before a feature is "done," it needs at minimum:
+
+- **P0 scenarios:** critical user flows that MUST work (blocking)
+- **P1 scenarios:** important flows that SHOULD work (non-blocking)
+- **Each scenario:** steps, expected result, pass/fail status, tester, date
+
+### UAT Template (create at `docs/uat/UAT_TEMPLATE.md`)
+
+```markdown
+# UAT Scenario Pack: [Project Name]
+
+## Pre-Conditions
+- [ ] App is running (dev or staging)
+- [ ] Test accounts exist
+- [ ] Test data is seeded
+
+## UAT-001: [Feature] — Happy Path
+**Priority:** P0
+**Steps:**
+1. [action]
+2. [action]
+**Expected:** [result]
+**Status:** PASS / FAIL / BLOCKED / NOT RUN
+**Tester:** ___ **Date:** ___
+```
+
+### UAT Tracking (create at `docs/uat/UAT_CHECKLIST.csv`)
+
+```csv
+UAT_ID,Feature,Priority,Status,Tester,Date,Defect_ID,Notes
+UAT-001,[Feature],P0,NOT RUN,,,,
+```
+
+### Gate Rule
+
+No feature is "complete" unless:
+- All P0 UAT scenarios are PASS, or
+- A product-owner waiver is documented for each failed/blocked P0
+
+---
+
+## Part 7: Failover & Production Resilience
+
+### Every Backend Must Include
+
+**Health check endpoint** (`/health` or `/healthz`):
+- Returns 200 when the service is healthy
+- Checks database connectivity
+- Checks critical external service reachability
+
+**Graceful shutdown:**
+- Handle SIGTERM/SIGINT
+- Stop accepting new requests
+- Drain active connections
+- Close database pools
+- Exit cleanly
+
+**Retry with backoff** for external calls:
+- Database connections: retry 3x with exponential backoff
+- External API calls: timeout (5-30s) + retry (2-3x) + fallback
+- AI/LLM calls: timeout (60s) + retry (1x) + rule-based fallback
+
+**Structured error responses** (never leak internals):
+- Production: `{ "error": "Something went wrong", "code": "INTERNAL" }`
+- Development: full stack trace (toggled by env var)
+
+### If Your App Uses AI/LLM
+
+Additionally include:
+- AI response validation (parse into typed schema, reject raw strings)
+- Fallback when AI is unavailable (rule-based or informative error)
+- Rate limit handling (queue or degrade gracefully)
+- PII redaction before any data leaves your infrastructure
+
+---
+
+## Part 8: Frontend/Backend Separation
+
+Always implement backend first, frontend second, with `/clear` between.
+
+```
+BACKEND TASK: [description]. Do NOT touch frontend files.
+```
+```
+FRONTEND TASK: [description]. Wire to existing API methods. Do NOT touch backend files.
+```
+
+---
+
+## Part 9: Complete Workflow
+
+```
+SPEC → PLAN → REVIEW → BRANCH → BACKEND → FRONTEND → TESTS → UAT CHECK → VERIFY → PR → PRE-DEPLOY → SHIP
+```
+
+Each step uses the corresponding prompt from `universal-prompt-library.md`.
+
+---
+
+## Quick Reference
+
+| What | Where | Loaded |
+|------|-------|--------|
+| Universal rules (~150 lines) | `CLAUDE.md` (root) | Every session |
+| Backend rules | `backend/CLAUDE.md` | In backend/ |
+| Frontend rules | `src/CLAUDE.md` | In src/ |
+| Test rules | `e2e/CLAUDE.md` | In e2e/ |
+| Domain knowledge | `.claude/skills/` | On demand |
+| Lint enforcement | PostToolUse hook | Every edit |
+| Validation gate | Stop hook | Every completion |
+| File protection | PreToolUse hook | Every write |
+| Spec audits | `.claude/commands/` | On demand |
+| Agent reviews | `.claude/agents/` | On demand |
+| UAT scenarios | `docs/uat/UAT_TEMPLATE.md` | Per feature |
+| UAT tracking | `docs/uat/UAT_CHECKLIST.csv` | Per release |
+| Resilience audit | `/project:audit-resilience` | Before deploy |
+| Pre-deploy smoke | `/project:pre-deploy` | Before deploy |