From ce2710e73c4cd74f306c51f131fce66f55a282b9 Mon Sep 17 00:00:00 2001 From: sjarmak Date: Mon, 22 Jun 2026 15:30:43 -0400 Subject: [PATCH] refactor(rules): ship Claude common rules on-demand, not auto-loaded Claude Code auto-loads rules/common/*.md, which contradicts this bundle's documented 'rules are NOT auto-loaded' design (coding-practices SKILL) and bloats every Claude session by ~8.7k tokens. render.mjs now ships the thin always-on house-rules.md (frontmatter autoload: claude) to rules/common/ and relocates the full per-topic detail to rules/reference/ (discoverable on demand via the coding-practices catalog). Language rules under rules// are unchanged. AGENTS.full.md skips the consolidation file so its content is not duplicated. Auto-loaded common footprint: ~8,690 -> ~1,640 tokens per session. --- AGENTS.md | 1 + build/render.mjs | 32 ++++- source/agents/architect.md | 2 +- source/agents/code-reviewer.md | 6 +- source/agents/tdd-guide.md | 2 +- source/rules/common/house-rules.md | 122 ++++++++++++++++++ source/skills/code-review/SKILL.md | 2 +- source/skills/coding-practices/SKILL.md | 14 +- source/skills/review/SKILL.md | 2 +- source/skills/slop-check/SKILL.md | 2 +- targets/claude/agents/architect.md | 2 +- targets/claude/agents/code-reviewer.md | 6 +- targets/claude/agents/tdd-guide.md | 2 +- targets/claude/rules/common/house-rules.md | 122 ++++++++++++++++++ .../agent-collaboration.md | 0 .../rules/{common => reference}/agents.md | 0 .../rules/{common => reference}/anti-slop.md | 0 .../{common => reference}/architecture.md | 0 .../augmented-coding-patterns.md | 0 .../{common => reference}/coding-style.md | 0 .../{common => reference}/context-layering.md | 0 .../development-workflow.md | 0 .../{common => reference}/git-workflow.md | 0 .../rules/{common => reference}/hooks.md | 0 .../rules/{common => reference}/patterns.md | 0 .../{common => reference}/performance.md | 0 .../rules/{common => reference}/security.md | 0 .../{common => reference}/skill-management.md | 0 .../{common => reference}/task-management.md | 0 .../rules/{common => reference}/testing.md | 0 targets/claude/skills/code-review/SKILL.md | 2 +- .../claude/skills/coding-practices/SKILL.md | 46 +++---- targets/claude/skills/review/SKILL.md | 2 +- targets/claude/skills/slop-check/SKILL.md | 2 +- targets/codex/AGENTS.md | 1 + targets/codex/agents/architect.md | 2 +- targets/codex/agents/code-reviewer.md | 6 +- targets/codex/agents/tdd-guide.md | 2 +- targets/codex/prompts/code-review.md | 2 +- targets/codex/prompts/slop-check.md | 2 +- 40 files changed, 329 insertions(+), 55 deletions(-) create mode 100644 source/rules/common/house-rules.md create mode 100644 targets/claude/rules/common/house-rules.md rename targets/claude/rules/{common => reference}/agent-collaboration.md (100%) rename targets/claude/rules/{common => reference}/agents.md (100%) rename targets/claude/rules/{common => reference}/anti-slop.md (100%) rename targets/claude/rules/{common => reference}/architecture.md (100%) rename targets/claude/rules/{common => reference}/augmented-coding-patterns.md (100%) rename targets/claude/rules/{common => reference}/coding-style.md (100%) rename targets/claude/rules/{common => reference}/context-layering.md (100%) rename targets/claude/rules/{common => reference}/development-workflow.md (100%) rename targets/claude/rules/{common => reference}/git-workflow.md (100%) rename targets/claude/rules/{common => reference}/hooks.md (100%) rename targets/claude/rules/{common => reference}/patterns.md (100%) rename targets/claude/rules/{common => reference}/performance.md (100%) rename targets/claude/rules/{common => reference}/security.md (100%) rename targets/claude/rules/{common => reference}/skill-management.md (100%) rename targets/claude/rules/{common => reference}/task-management.md (100%) rename targets/claude/rules/{common => reference}/testing.md (100%) diff --git a/AGENTS.md b/AGENTS.md index 2a7b2ef..c207dfa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,7 @@ Each is a section (matched by heading) in `AGENTS.full.md`: - **Context Layering** (`common/context-layering.md`) — The four context layers an agent reads, and the one-fact-one-layer rule that keeps AGENTS.md thin and free of conflict with memory. - **Development Workflow** (`common/development-workflow.md`) - **Git Workflow** (`common/git-workflow.md`) +- **House Rules (always-on)** (`common/house-rules.md`) — Always-on essentials — autonomy boundary, output discipline, coding/architecture/security standards, ZFC, anti-slop trigger. Detailed catalogs are in rules/reference/ (on-demand). - **Common Patterns** (`common/patterns.md`) - **Performance Optimization** (`common/performance.md`) - **Security Guidelines** (`common/security.md`) diff --git a/build/render.mjs b/build/render.mjs index 57d3241..533728d 100644 --- a/build/render.mjs +++ b/build/render.mjs @@ -57,10 +57,24 @@ mkdirp(TARGETS); // targets/claude: native Claude Code layout // ========================================================================= const C = path.join(TARGETS, 'claude'); -// rules: all languages in manifest +// rules: detailed rule files are meant to be read on demand, not auto-loaded. +// Claude Code DOES auto-load rules/common/*.md, so the full common set ships to +// rules/reference/ (a sibling dir, not auto-loaded like rules//), and only +// files marked `autoload: claude` (the thin house-rules.md) stay in rules/common/ +// to load every session. Language rules stay under rules// (on-demand). for (const lang of Object.keys(manifest.rules)) { if (lang.startsWith('$')) continue; - copyDir(path.join(SRC, 'rules', lang), path.join(C, 'rules', lang)); + if (lang !== 'common') { + copyDir(path.join(SRC, 'rules', lang), path.join(C, 'rules', lang)); + continue; + } + const commonSrc = path.join(SRC, 'rules', 'common'); + for (const f of fs.readdirSync(commonSrc).filter(x => x.endsWith('.md'))) { + const raw = fs.readFileSync(path.join(commonSrc, f), 'utf8'); + const { data } = parse(raw); + const sub = data.autoload === 'claude' ? 'common' : 'reference'; + write(path.join(C, 'rules', sub, f), raw); + } } // agents: universal + claude for (const [name, scope] of Object.entries(manifest.agents)) { @@ -94,7 +108,14 @@ if (fs.existsSync(cpPath)) { const dir = path.join(SRC, 'rules', lang); catalog.push('', `### ${lang === 'common' ? 'Common (all languages)' : lang}`, ''); for (const f of fs.readdirSync(dir).filter(x => x.endsWith('.md')).sort()) { - catalog.push(`- \`.claude/rules/${lang}/${f}\` — ${ruleEntry(path.join(dir, f))}`); + // common detail ships to rules/reference/; autoload files load every + // session and are not on-demand catalog entries. + if (lang === 'common') { + if (parse(fs.readFileSync(path.join(dir, f), 'utf8')).data.autoload === 'claude') continue; + catalog.push(`- \`.claude/rules/reference/${f}\` — ${ruleEntry(path.join(dir, f))}`); + } else { + catalog.push(`- \`.claude/rules/${lang}/${f}\` — ${ruleEntry(path.join(dir, f))}`); + } } } write(cpPath, fs.readFileSync(cpPath, 'utf8').replace('', catalog.join('\n').trim())); @@ -201,9 +222,12 @@ const ruleOverrides = manifest.rule_overrides || {}; const commonDir = path.join(SRC, 'rules', 'common'); for (const f of fs.readdirSync(commonDir).sort()) { if (!f.endsWith('.md')) continue; + const { data, body } = parse(fs.readFileSync(path.join(commonDir, f), 'utf8')); + // autoload files are a target-specific consolidation of the others — skip them + // here so their content isn't duplicated alongside the full per-topic text. + if (data.autoload) continue; // claude/codex-scoped rule files ship to their target but stay out of universal AGENTS.md if ((ruleOverrides[`common/${f}`] || 'universal') !== 'universal') continue; - const { body } = parse(fs.readFileSync(path.join(commonDir, f), 'utf8')); parts.push(body.trim()); parts.push(''); } diff --git a/source/agents/architect.md b/source/agents/architect.md index 418d0c3..31d9655 100644 --- a/source/agents/architect.md +++ b/source/agents/architect.md @@ -51,7 +51,7 @@ For each design decision, document: ## Architectural Principles -> Global standards live in `~/.claude/rules/common/architecture.md`. Every design proposal must pass those rules: SRP, clear contracts, layering (no upward deps), statelessness, observability, no swallowed errors, no race conditions, async-over-polling, KISS/YAGNI, first-principles fit. +> Global standards live in `~/.claude/rules/reference/architecture.md`. Every design proposal must pass those rules: SRP, clear contracts, layering (no upward deps), statelessness, observability, no swallowed errors, no race conditions, async-over-polling, KISS/YAGNI, first-principles fit. ### 1. Modularity & Separation of Concerns diff --git a/source/agents/code-reviewer.md b/source/agents/code-reviewer.md index 99258ff..c05b514 100644 --- a/source/agents/code-reviewer.md +++ b/source/agents/code-reviewer.md @@ -173,7 +173,7 @@ const usersWithPosts = await db.query(` ### Architecture Principles (HIGH) -Check against `~/.claude/rules/common/architecture.md`: +Check against `~/.claude/rules/reference/architecture.md`: - **SRP violations**: Modules with multiple reasons to change; classes named "Manager"/"Helper"/"Util" that accumulate unrelated methods - **Layering violations**: Upward dependencies (lower layer importing from a higher one), presentation logic in data layer, business rules leaking into controllers @@ -189,7 +189,7 @@ Check against `~/.claude/rules/common/architecture.md`: ### AI Slop & Erosion (HIGH) -Check against `~/.claude/rules/common/anti-slop.md`. These are the patterns AI-generated and iteratively-extended code accumulates — weight your attention toward code that **extends** an existing function/module rather than greenfield additions: +Check against `~/.claude/rules/reference/anti-slop.md`. These are the patterns AI-generated and iteratively-extended code accumulates — weight your attention toward code that **extends** an existing function/module rather than greenfield additions: - **Documentation noise**: narration comments ("Step 1:"), docstrings that restate the function name, entry/exit logging in short functions - **Overengineering**: single-implementer interfaces, single-entry registries, factories that return a constant, strategies set once and never varied, primitive/monadic wrappers with no behavior @@ -267,7 +267,7 @@ When reviewing AI-generated changes, prioritize: 2. Security assumptions and trust boundaries 3. Hidden coupling or accidental architecture drift 4. Unnecessary model-cost-inducing complexity -5. Slop and erosion signatures — run the **AI Slop & Erosion** checklist above (`~/.claude/rules/common/anti-slop.md`). AI-extended code is the highest-yield surface for the overengineering, documentation-noise, and error-obscuring patterns. +5. Slop and erosion signatures — run the **AI Slop & Erosion** checklist above (`~/.claude/rules/reference/anti-slop.md`). AI-extended code is the highest-yield surface for the overengineering, documentation-noise, and error-obscuring patterns. Cost-awareness check: diff --git a/source/agents/tdd-guide.md b/source/agents/tdd-guide.md index 565c55d..ef5912f 100644 --- a/source/agents/tdd-guide.md +++ b/source/agents/tdd-guide.md @@ -7,7 +7,7 @@ model: sonnet You are a Test-Driven Development (TDD) specialist who ensures all code is developed test-first with comprehensive coverage. -> TDD alignment: `~/.claude/rules/common/architecture.md` treats "hard to test" as a design smell, not a test-writing problem. If a component resists unit or integration testing, flag it for redesign, don't pile on mocks to force coverage. Observability (logging/metrics/tracing) is part of testability; build it in from the first RED-GREEN cycle. +> TDD alignment: `~/.claude/rules/reference/architecture.md` treats "hard to test" as a design smell, not a test-writing problem. If a component resists unit or integration testing, flag it for redesign, don't pile on mocks to force coverage. Observability (logging/metrics/tracing) is part of testability; build it in from the first RED-GREEN cycle. ## Your Role diff --git a/source/rules/common/house-rules.md b/source/rules/common/house-rules.md new file mode 100644 index 0000000..390afb9 --- /dev/null +++ b/source/rules/common/house-rules.md @@ -0,0 +1,122 @@ +--- +summary: Always-on essentials — autonomy boundary, output discipline, coding/architecture/security standards, ZFC, anti-slop trigger. Detailed catalogs are in rules/reference/ (on-demand). +autoload: claude +--- + +# House Rules (always-on) + +The essential, always-loaded conventions. Detailed catalogs live in **on-demand +skills** — don't inline them: code-review depth → `/review` + `code-reviewer` +agent; slop/erosion catalog → `/slop-check`; language specifics → +`-patterns` / `-review` skills and `rules//`. The agent roster +is already provided in session context — never duplicate it here. + +## Collaboration & Autonomy + +**Autonomy boundary** — internal work is autonomous; external artifacts always +need explicit per-action approval (even if a similar action was approved earlier +in the session). + +- _Internal (proceed between sub-steps once a phase starts):_ tests, sweeps, + linters, builds, local CI, polling, multi-file edits in a worktree you own, + sub-agent dispatch, bead claims, worktree/branch creation. +- _External (STOP and confirm per-action):_ `git push` (any form), `gh pr +create|merge|edit|close|ready`, `gh issue create|edit|close|comment`, `gh +release …`, Slack/email/LINE/Messenger/Discord replies, any post to an + external service, `git push --force` / `branch -D` on shared refs. + +**Preview before execute** — when the user asks for an artifact she'll act on +(PR body, issue text, commit message, reply), produce it as text and STOP. Only +call the publishing tool on an explicit publish verb ("send it", "open it", +"file it", "push it", "post it", "ship it"). "What's the PR body?" → output +text, do NOT run `gh pr create`. + +**Parallel by default** — dispatch ≥2 independent agents in one message. Non- +trivial code review = 2 independent reviewers + a Codex meta-review unless told +otherwise; route to Codex when available. + +**Receiving review** — evaluate technically; the reviewer can be wrong, the +codebase is the authority. Per item: read → restate → verify against the code → +decide → respond → implement one at a time. Never open with "You're absolutely +right!" before verifying. Push back with technical reasoning when the feedback +is wrong for this codebase. + +**Output discipline** — no effort/time estimates in orchestrated work; no +decision-framework preambles when the prompt contains a directive ("just do X"); +no trailing summaries of what you did; no upfront "I'll do A then B" narration. +State results and decisions as they happen. + +**Tests ship with fixes** — the test lives in the same commit as the source +change, not a follow-up. + +**Verifier role clamp** — when spawning a verification agent, open with: "You +are a verification agent. You did NOT write this code. ACTIVELY TEST each +acceptance criterion — do not just read." Then enumerate explicit verification +commands per criterion. + +## Coding Standards + +- **Immutability** by default — return new objects, don't mutate in place. + Prefer **non-nullable** variables; introduce null only where absence is + semantically meaningful. +- **Files**: many small, focused files over few large ones. 200–400 lines + typical, 800 max. No deep nesting (>4 levels). Functions <50 lines. +- **Errors**: handle explicitly at every level; never silently swallow. Don't + mask failures with default values or bug-hiding timeouts. Timeouts are allowed + at trust boundaries (HTTP, DB, subprocess) but must propagate a real error. +- **Input validation** at every system boundary; never trust external data + (API responses, user input, file content). Fail fast with clear messages. +- **No placeholder code** — no `throw "not implemented"`, no fake returns, no + TODO standing in for in-scope work. **No commented-out history** — git holds + it; delete removed code outright. +- **Codebase ownership** — fix issues you discover (broken tests, build errors, + stale refs, security) regardless of the current ticket's scope. + +## Architecture + +SRP (split on reasons-to-change), DRY (rule of three — don't extract until the +duplication is real), KISS, YAGNI, low coupling / high cohesion, layered +dependencies pointing one direction. Run a first-principles check before major +features touching the core domain. + +**Zero Framework Cognition (ZFC)** — in AI-orchestration code, the application +layer is plumbing; delegate all _reasoning_ to models. _Allowed in code:_ IO, +schema/structural validation, policy enforcement (budgets, limits, timeouts, +sandboxing), mechanical transforms, state/lifecycle, deterministic math. +_Forbidden (delegate to model):_ semantic classification, heuristic scoring with +hardcoded thresholds, keyword/regex meaning-detection, planning/composition +decisions, quality judgments beyond structural checks. Applies to AI- +orchestration code, not CRUD/infra/hot paths. + +## Anti-Slop (extend cleanly) + +On any change that **extends existing code**: re-read the whole touched +function/module (not just the diff hunk), ask "would I write this from scratch +with today's requirements?", and prefer a net-negative diff that meets the +requirement over a net-positive one. Full signature catalog → `/slop-check`. + +## Workflow + +- **Research & reuse before new code**: GitHub code search (`gh search +repos|code`) → primary/Context7 docs → Exa (only if the first two fall short). + Check package registries; prefer porting a proven implementation over net-new. +- **TDD**: write the failing test first (RED → GREEN → refactor); target 80%+ + coverage (unit + integration + E2E for critical flows). Plan complex/refactor + work first (`planner`); run `code-reviewer` after writing code. +- **Git**: conventional commit types (`feat|fix|refactor|docs|test|chore|perf| +ci`). Attribution is disabled globally. For PRs, draft from the full diff + (`git diff ...HEAD`), not just the last commit; include a test plan. + +## Security (pre-commit) + +No hardcoded secrets (env vars / secret manager; validate presence at startup). +Validate all inputs; parameterized queries (no SQL injection); sanitize HTML (no +XSS); CSRF protection; verify authz; rate-limit endpoints; error messages don't +leak sensitive data. On finding a security issue: stop, fix CRITICAL before +continuing, rotate exposed secrets, sweep for similar. + +## Performance & Model Tiering + +Tier work by cognitive load: routine/high-frequency → Haiku, main development & +orchestration → Sonnet, deepest reasoning/architecture → Opus. Avoid the last +20% of the context window for large refactors and multi-file features. diff --git a/source/skills/code-review/SKILL.md b/source/skills/code-review/SKILL.md index 4c98b53..8c67f87 100644 --- a/source/skills/code-review/SKILL.md +++ b/source/skills/code-review/SKILL.md @@ -25,7 +25,7 @@ Comprehensive security and quality review of uncommitted changes: - TODO/FIXME comments - Missing JSDoc for public APIs -**AI Slop & Erosion (HIGH)** — see the `anti-slop` rule (`rules/common/anti-slop.md`), weight toward code that extends existing modules: +**AI Slop & Erosion (HIGH)** — see the `anti-slop` rule (`rules/reference/anti-slop.md`), weight toward code that extends existing modules: - Overengineering: single-implementer interfaces, single-entry registries, factories returning a constant - Documentation noise: narration comments, docstrings that restate the function name diff --git a/source/skills/coding-practices/SKILL.md b/source/skills/coding-practices/SKILL.md index fec3222..cd2dc14 100644 --- a/source/skills/coding-practices/SKILL.md +++ b/source/skills/coding-practices/SKILL.md @@ -1,18 +1,20 @@ --- name: coding-practices summary: Discovery index for this project's coding-practice rules; load it to find the right rule, then read that rule file on demand. -description: Index of this project's coding-practice rules — architecture, coding style, testing, security, git workflow, task management, context layering, anti-slop, performance, and language-specific rules. The rules ship as files under .claude/rules/ and are NOT auto-loaded into context; invoke this skill when you need the project's standards for a task, then open the specific rule file it points to. Keeps the standards discoverable without loading all of them by default. +description: Index of this project's coding-practice rules — architecture, coding style, testing, security, git workflow, task management, context layering, anti-slop, performance, and language-specific rules. The thin always-on essentials live in .claude/rules/common/house-rules.md; the full per-topic detail ships under .claude/rules/reference/ and .claude/rules// and is read on demand. Invoke this skill when you need the project's standards for a task, then open the specific rule file it points to. origin: agentic-coding-practices scope: claude --- # Coding Practices Index -This project's coding standards live as individual rule files under -`.claude/rules/`. They are **not** loaded into context automatically — that keeps -the context window lean and nothing active that you didn't ask for. Read the one -rule relevant to your current task, when you need it. This skill is the catalog of -what's available and where to find it. +The always-on essentials load every session from +`.claude/rules/common/house-rules.md` (autonomy boundary, output discipline, +coding/architecture/security standards, ZFC, the anti-slop trigger). The **full +per-topic detail** is **not** auto-loaded — it ships under `.claude/rules/reference/` +(common topics) and `.claude/rules//` (language rules) to keep the context +window lean. Read the one rule relevant to your current task, when you need it. +This skill is the catalog of that on-demand detail. ## How to use diff --git a/source/skills/review/SKILL.md b/source/skills/review/SKILL.md index c0f48f7..786d065 100644 --- a/source/skills/review/SKILL.md +++ b/source/skills/review/SKILL.md @@ -32,7 +32,7 @@ Hacky patterns to flag: - **Stringly-typed code**: raw strings where constants, enums, or branded types already exist - **Unnecessary comments**: comments narrating what the code does (well-named identifiers already do that) or referencing the task, keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds) - **Boundary violations**: directories or modules with architectural rules (search for `boundary_test.go`, `arch-test`, ESLint `no-restricted-imports`, etc.) that the change might violate -- **Slop & erosion** (`rules/common/anti-slop.md`): single-implementer interfaces / single-entry registries / factories returning a constant (overengineering), caching of constants or parallelism for tiny collections (premature optimization), narration comments and echo docstrings (documentation noise), success-booleans / generic error messages / retries that swallow failures (error obscuring), silent fallbacks and auto-correction (hidden behavior), and unrequested features or no-op validation (spec deviation). Weight toward code that **extends** an existing module — apply the erosion test: _would this look like this if written from scratch with today's requirements?_ +- **Slop & erosion** (`rules/reference/anti-slop.md`): single-implementer interfaces / single-entry registries / factories returning a constant (overengineering), caching of constants or parallelism for tiny collections (premature optimization), narration comments and echo docstrings (documentation noise), success-booleans / generic error messages / retries that swallow failures (error obscuring), silent fallbacks and auto-correction (hidden behavior), and unrequested features or no-op validation (spec deviation). Weight toward code that **extends** an existing module — apply the erosion test: _would this look like this if written from scratch with today's requirements?_ ### Agent 3: Efficiency (general-purpose) diff --git a/source/skills/slop-check/SKILL.md b/source/skills/slop-check/SKILL.md index 7f4dd9e..f67d2d7 100644 --- a/source/skills/slop-check/SKILL.md +++ b/source/skills/slop-check/SKILL.md @@ -29,7 +29,7 @@ For the extended surface, **read the whole enclosing function/module**, not just ## Phase 2: Judge against the rubric (the model judges, not regex) -The rubric is the catalog in the `anti-slop` rule (`rules/common/anti-slop.md`, the SlopCodeBench 45-criterion judge, grouped). These are **semantic** judgments — do not grep for them; read and reason. For a large or cross-file diff, dispatch a general-purpose reviewer with a role clamp ("You are a verification agent; you did NOT write this code; actively read the enclosing modules") and the anti-slop catalog; otherwise judge directly. +The rubric is the catalog in the `anti-slop` rule (`rules/reference/anti-slop.md`, the SlopCodeBench 45-criterion judge, grouped). These are **semantic** judgments — do not grep for them; read and reason. For a large or cross-file diff, dispatch a general-purpose reviewer with a role clamp ("You are a verification agent; you did NOT write this code; actively read the enclosing modules") and the anti-slop catalog; otherwise judge directly. For each touched region, walk the catalog groups and record concrete hits with `file:line`: diff --git a/targets/claude/agents/architect.md b/targets/claude/agents/architect.md index 418d0c3..31d9655 100644 --- a/targets/claude/agents/architect.md +++ b/targets/claude/agents/architect.md @@ -51,7 +51,7 @@ For each design decision, document: ## Architectural Principles -> Global standards live in `~/.claude/rules/common/architecture.md`. Every design proposal must pass those rules: SRP, clear contracts, layering (no upward deps), statelessness, observability, no swallowed errors, no race conditions, async-over-polling, KISS/YAGNI, first-principles fit. +> Global standards live in `~/.claude/rules/reference/architecture.md`. Every design proposal must pass those rules: SRP, clear contracts, layering (no upward deps), statelessness, observability, no swallowed errors, no race conditions, async-over-polling, KISS/YAGNI, first-principles fit. ### 1. Modularity & Separation of Concerns diff --git a/targets/claude/agents/code-reviewer.md b/targets/claude/agents/code-reviewer.md index 99258ff..c05b514 100644 --- a/targets/claude/agents/code-reviewer.md +++ b/targets/claude/agents/code-reviewer.md @@ -173,7 +173,7 @@ const usersWithPosts = await db.query(` ### Architecture Principles (HIGH) -Check against `~/.claude/rules/common/architecture.md`: +Check against `~/.claude/rules/reference/architecture.md`: - **SRP violations**: Modules with multiple reasons to change; classes named "Manager"/"Helper"/"Util" that accumulate unrelated methods - **Layering violations**: Upward dependencies (lower layer importing from a higher one), presentation logic in data layer, business rules leaking into controllers @@ -189,7 +189,7 @@ Check against `~/.claude/rules/common/architecture.md`: ### AI Slop & Erosion (HIGH) -Check against `~/.claude/rules/common/anti-slop.md`. These are the patterns AI-generated and iteratively-extended code accumulates — weight your attention toward code that **extends** an existing function/module rather than greenfield additions: +Check against `~/.claude/rules/reference/anti-slop.md`. These are the patterns AI-generated and iteratively-extended code accumulates — weight your attention toward code that **extends** an existing function/module rather than greenfield additions: - **Documentation noise**: narration comments ("Step 1:"), docstrings that restate the function name, entry/exit logging in short functions - **Overengineering**: single-implementer interfaces, single-entry registries, factories that return a constant, strategies set once and never varied, primitive/monadic wrappers with no behavior @@ -267,7 +267,7 @@ When reviewing AI-generated changes, prioritize: 2. Security assumptions and trust boundaries 3. Hidden coupling or accidental architecture drift 4. Unnecessary model-cost-inducing complexity -5. Slop and erosion signatures — run the **AI Slop & Erosion** checklist above (`~/.claude/rules/common/anti-slop.md`). AI-extended code is the highest-yield surface for the overengineering, documentation-noise, and error-obscuring patterns. +5. Slop and erosion signatures — run the **AI Slop & Erosion** checklist above (`~/.claude/rules/reference/anti-slop.md`). AI-extended code is the highest-yield surface for the overengineering, documentation-noise, and error-obscuring patterns. Cost-awareness check: diff --git a/targets/claude/agents/tdd-guide.md b/targets/claude/agents/tdd-guide.md index 565c55d..ef5912f 100644 --- a/targets/claude/agents/tdd-guide.md +++ b/targets/claude/agents/tdd-guide.md @@ -7,7 +7,7 @@ model: sonnet You are a Test-Driven Development (TDD) specialist who ensures all code is developed test-first with comprehensive coverage. -> TDD alignment: `~/.claude/rules/common/architecture.md` treats "hard to test" as a design smell, not a test-writing problem. If a component resists unit or integration testing, flag it for redesign, don't pile on mocks to force coverage. Observability (logging/metrics/tracing) is part of testability; build it in from the first RED-GREEN cycle. +> TDD alignment: `~/.claude/rules/reference/architecture.md` treats "hard to test" as a design smell, not a test-writing problem. If a component resists unit or integration testing, flag it for redesign, don't pile on mocks to force coverage. Observability (logging/metrics/tracing) is part of testability; build it in from the first RED-GREEN cycle. ## Your Role diff --git a/targets/claude/rules/common/house-rules.md b/targets/claude/rules/common/house-rules.md new file mode 100644 index 0000000..390afb9 --- /dev/null +++ b/targets/claude/rules/common/house-rules.md @@ -0,0 +1,122 @@ +--- +summary: Always-on essentials — autonomy boundary, output discipline, coding/architecture/security standards, ZFC, anti-slop trigger. Detailed catalogs are in rules/reference/ (on-demand). +autoload: claude +--- + +# House Rules (always-on) + +The essential, always-loaded conventions. Detailed catalogs live in **on-demand +skills** — don't inline them: code-review depth → `/review` + `code-reviewer` +agent; slop/erosion catalog → `/slop-check`; language specifics → +`-patterns` / `-review` skills and `rules//`. The agent roster +is already provided in session context — never duplicate it here. + +## Collaboration & Autonomy + +**Autonomy boundary** — internal work is autonomous; external artifacts always +need explicit per-action approval (even if a similar action was approved earlier +in the session). + +- _Internal (proceed between sub-steps once a phase starts):_ tests, sweeps, + linters, builds, local CI, polling, multi-file edits in a worktree you own, + sub-agent dispatch, bead claims, worktree/branch creation. +- _External (STOP and confirm per-action):_ `git push` (any form), `gh pr +create|merge|edit|close|ready`, `gh issue create|edit|close|comment`, `gh +release …`, Slack/email/LINE/Messenger/Discord replies, any post to an + external service, `git push --force` / `branch -D` on shared refs. + +**Preview before execute** — when the user asks for an artifact she'll act on +(PR body, issue text, commit message, reply), produce it as text and STOP. Only +call the publishing tool on an explicit publish verb ("send it", "open it", +"file it", "push it", "post it", "ship it"). "What's the PR body?" → output +text, do NOT run `gh pr create`. + +**Parallel by default** — dispatch ≥2 independent agents in one message. Non- +trivial code review = 2 independent reviewers + a Codex meta-review unless told +otherwise; route to Codex when available. + +**Receiving review** — evaluate technically; the reviewer can be wrong, the +codebase is the authority. Per item: read → restate → verify against the code → +decide → respond → implement one at a time. Never open with "You're absolutely +right!" before verifying. Push back with technical reasoning when the feedback +is wrong for this codebase. + +**Output discipline** — no effort/time estimates in orchestrated work; no +decision-framework preambles when the prompt contains a directive ("just do X"); +no trailing summaries of what you did; no upfront "I'll do A then B" narration. +State results and decisions as they happen. + +**Tests ship with fixes** — the test lives in the same commit as the source +change, not a follow-up. + +**Verifier role clamp** — when spawning a verification agent, open with: "You +are a verification agent. You did NOT write this code. ACTIVELY TEST each +acceptance criterion — do not just read." Then enumerate explicit verification +commands per criterion. + +## Coding Standards + +- **Immutability** by default — return new objects, don't mutate in place. + Prefer **non-nullable** variables; introduce null only where absence is + semantically meaningful. +- **Files**: many small, focused files over few large ones. 200–400 lines + typical, 800 max. No deep nesting (>4 levels). Functions <50 lines. +- **Errors**: handle explicitly at every level; never silently swallow. Don't + mask failures with default values or bug-hiding timeouts. Timeouts are allowed + at trust boundaries (HTTP, DB, subprocess) but must propagate a real error. +- **Input validation** at every system boundary; never trust external data + (API responses, user input, file content). Fail fast with clear messages. +- **No placeholder code** — no `throw "not implemented"`, no fake returns, no + TODO standing in for in-scope work. **No commented-out history** — git holds + it; delete removed code outright. +- **Codebase ownership** — fix issues you discover (broken tests, build errors, + stale refs, security) regardless of the current ticket's scope. + +## Architecture + +SRP (split on reasons-to-change), DRY (rule of three — don't extract until the +duplication is real), KISS, YAGNI, low coupling / high cohesion, layered +dependencies pointing one direction. Run a first-principles check before major +features touching the core domain. + +**Zero Framework Cognition (ZFC)** — in AI-orchestration code, the application +layer is plumbing; delegate all _reasoning_ to models. _Allowed in code:_ IO, +schema/structural validation, policy enforcement (budgets, limits, timeouts, +sandboxing), mechanical transforms, state/lifecycle, deterministic math. +_Forbidden (delegate to model):_ semantic classification, heuristic scoring with +hardcoded thresholds, keyword/regex meaning-detection, planning/composition +decisions, quality judgments beyond structural checks. Applies to AI- +orchestration code, not CRUD/infra/hot paths. + +## Anti-Slop (extend cleanly) + +On any change that **extends existing code**: re-read the whole touched +function/module (not just the diff hunk), ask "would I write this from scratch +with today's requirements?", and prefer a net-negative diff that meets the +requirement over a net-positive one. Full signature catalog → `/slop-check`. + +## Workflow + +- **Research & reuse before new code**: GitHub code search (`gh search +repos|code`) → primary/Context7 docs → Exa (only if the first two fall short). + Check package registries; prefer porting a proven implementation over net-new. +- **TDD**: write the failing test first (RED → GREEN → refactor); target 80%+ + coverage (unit + integration + E2E for critical flows). Plan complex/refactor + work first (`planner`); run `code-reviewer` after writing code. +- **Git**: conventional commit types (`feat|fix|refactor|docs|test|chore|perf| +ci`). Attribution is disabled globally. For PRs, draft from the full diff + (`git diff ...HEAD`), not just the last commit; include a test plan. + +## Security (pre-commit) + +No hardcoded secrets (env vars / secret manager; validate presence at startup). +Validate all inputs; parameterized queries (no SQL injection); sanitize HTML (no +XSS); CSRF protection; verify authz; rate-limit endpoints; error messages don't +leak sensitive data. On finding a security issue: stop, fix CRITICAL before +continuing, rotate exposed secrets, sweep for similar. + +## Performance & Model Tiering + +Tier work by cognitive load: routine/high-frequency → Haiku, main development & +orchestration → Sonnet, deepest reasoning/architecture → Opus. Avoid the last +20% of the context window for large refactors and multi-file features. diff --git a/targets/claude/rules/common/agent-collaboration.md b/targets/claude/rules/reference/agent-collaboration.md similarity index 100% rename from targets/claude/rules/common/agent-collaboration.md rename to targets/claude/rules/reference/agent-collaboration.md diff --git a/targets/claude/rules/common/agents.md b/targets/claude/rules/reference/agents.md similarity index 100% rename from targets/claude/rules/common/agents.md rename to targets/claude/rules/reference/agents.md diff --git a/targets/claude/rules/common/anti-slop.md b/targets/claude/rules/reference/anti-slop.md similarity index 100% rename from targets/claude/rules/common/anti-slop.md rename to targets/claude/rules/reference/anti-slop.md diff --git a/targets/claude/rules/common/architecture.md b/targets/claude/rules/reference/architecture.md similarity index 100% rename from targets/claude/rules/common/architecture.md rename to targets/claude/rules/reference/architecture.md diff --git a/targets/claude/rules/common/augmented-coding-patterns.md b/targets/claude/rules/reference/augmented-coding-patterns.md similarity index 100% rename from targets/claude/rules/common/augmented-coding-patterns.md rename to targets/claude/rules/reference/augmented-coding-patterns.md diff --git a/targets/claude/rules/common/coding-style.md b/targets/claude/rules/reference/coding-style.md similarity index 100% rename from targets/claude/rules/common/coding-style.md rename to targets/claude/rules/reference/coding-style.md diff --git a/targets/claude/rules/common/context-layering.md b/targets/claude/rules/reference/context-layering.md similarity index 100% rename from targets/claude/rules/common/context-layering.md rename to targets/claude/rules/reference/context-layering.md diff --git a/targets/claude/rules/common/development-workflow.md b/targets/claude/rules/reference/development-workflow.md similarity index 100% rename from targets/claude/rules/common/development-workflow.md rename to targets/claude/rules/reference/development-workflow.md diff --git a/targets/claude/rules/common/git-workflow.md b/targets/claude/rules/reference/git-workflow.md similarity index 100% rename from targets/claude/rules/common/git-workflow.md rename to targets/claude/rules/reference/git-workflow.md diff --git a/targets/claude/rules/common/hooks.md b/targets/claude/rules/reference/hooks.md similarity index 100% rename from targets/claude/rules/common/hooks.md rename to targets/claude/rules/reference/hooks.md diff --git a/targets/claude/rules/common/patterns.md b/targets/claude/rules/reference/patterns.md similarity index 100% rename from targets/claude/rules/common/patterns.md rename to targets/claude/rules/reference/patterns.md diff --git a/targets/claude/rules/common/performance.md b/targets/claude/rules/reference/performance.md similarity index 100% rename from targets/claude/rules/common/performance.md rename to targets/claude/rules/reference/performance.md diff --git a/targets/claude/rules/common/security.md b/targets/claude/rules/reference/security.md similarity index 100% rename from targets/claude/rules/common/security.md rename to targets/claude/rules/reference/security.md diff --git a/targets/claude/rules/common/skill-management.md b/targets/claude/rules/reference/skill-management.md similarity index 100% rename from targets/claude/rules/common/skill-management.md rename to targets/claude/rules/reference/skill-management.md diff --git a/targets/claude/rules/common/task-management.md b/targets/claude/rules/reference/task-management.md similarity index 100% rename from targets/claude/rules/common/task-management.md rename to targets/claude/rules/reference/task-management.md diff --git a/targets/claude/rules/common/testing.md b/targets/claude/rules/reference/testing.md similarity index 100% rename from targets/claude/rules/common/testing.md rename to targets/claude/rules/reference/testing.md diff --git a/targets/claude/skills/code-review/SKILL.md b/targets/claude/skills/code-review/SKILL.md index 4c98b53..8c67f87 100644 --- a/targets/claude/skills/code-review/SKILL.md +++ b/targets/claude/skills/code-review/SKILL.md @@ -25,7 +25,7 @@ Comprehensive security and quality review of uncommitted changes: - TODO/FIXME comments - Missing JSDoc for public APIs -**AI Slop & Erosion (HIGH)** — see the `anti-slop` rule (`rules/common/anti-slop.md`), weight toward code that extends existing modules: +**AI Slop & Erosion (HIGH)** — see the `anti-slop` rule (`rules/reference/anti-slop.md`), weight toward code that extends existing modules: - Overengineering: single-implementer interfaces, single-entry registries, factories returning a constant - Documentation noise: narration comments, docstrings that restate the function name diff --git a/targets/claude/skills/coding-practices/SKILL.md b/targets/claude/skills/coding-practices/SKILL.md index 9202da6..60d34a2 100644 --- a/targets/claude/skills/coding-practices/SKILL.md +++ b/targets/claude/skills/coding-practices/SKILL.md @@ -1,18 +1,20 @@ --- name: coding-practices summary: Discovery index for this project's coding-practice rules; load it to find the right rule, then read that rule file on demand. -description: Index of this project's coding-practice rules — architecture, coding style, testing, security, git workflow, task management, context layering, anti-slop, performance, and language-specific rules. The rules ship as files under .claude/rules/ and are NOT auto-loaded into context; invoke this skill when you need the project's standards for a task, then open the specific rule file it points to. Keeps the standards discoverable without loading all of them by default. +description: Index of this project's coding-practice rules — architecture, coding style, testing, security, git workflow, task management, context layering, anti-slop, performance, and language-specific rules. The thin always-on essentials live in .claude/rules/common/house-rules.md; the full per-topic detail ships under .claude/rules/reference/ and .claude/rules// and is read on demand. Invoke this skill when you need the project's standards for a task, then open the specific rule file it points to. origin: agentic-coding-practices scope: claude --- # Coding Practices Index -This project's coding standards live as individual rule files under -`.claude/rules/`. They are **not** loaded into context automatically — that keeps -the context window lean and nothing active that you didn't ask for. Read the one -rule relevant to your current task, when you need it. This skill is the catalog of -what's available and where to find it. +The always-on essentials load every session from +`.claude/rules/common/house-rules.md` (autonomy boundary, output discipline, +coding/architecture/security standards, ZFC, the anti-slop trigger). The **full +per-topic detail** is **not** auto-loaded — it ships under `.claude/rules/reference/` +(common topics) and `.claude/rules//` (language rules) to keep the context +window lean. Read the one rule relevant to your current task, when you need it. +This skill is the catalog of that on-demand detail. ## How to use @@ -26,22 +28,22 @@ what's available and where to find it. ### Common (all languages) -- `.claude/rules/common/agent-collaboration.md` — Agent Collaboration -- `.claude/rules/common/agents.md` — Agent Orchestration -- `.claude/rules/common/anti-slop.md` — Anti-Slop & Code Erosion -- `.claude/rules/common/architecture.md` — Architecture Principles -- `.claude/rules/common/augmented-coding-patterns.md` — Augmented Coding Patterns -- `.claude/rules/common/coding-style.md` — Coding Style -- `.claude/rules/common/context-layering.md` — The four context layers an agent reads, and the one-fact-one-layer rule that keeps AGENTS.md thin and free of conflict with memory. -- `.claude/rules/common/development-workflow.md` — Development Workflow -- `.claude/rules/common/git-workflow.md` — Git Workflow -- `.claude/rules/common/hooks.md` — Hooks System -- `.claude/rules/common/patterns.md` — Common Patterns -- `.claude/rules/common/performance.md` — Performance Optimization -- `.claude/rules/common/security.md` — Security Guidelines -- `.claude/rules/common/skill-management.md` — Discover, vet, and expose agent skills on demand with skillager, so the right skills are available per task without loading every skill into every chat. -- `.claude/rules/common/task-management.md` — Track multi-step agent work in a durable, dependency-aware task store; prefer the lightest non-invasive backend (SQLite + JSONL) and only add heavier sync when you actually need it. -- `.claude/rules/common/testing.md` — Testing Requirements +- `.claude/rules/reference/agent-collaboration.md` — Agent Collaboration +- `.claude/rules/reference/agents.md` — Agent Orchestration +- `.claude/rules/reference/anti-slop.md` — Anti-Slop & Code Erosion +- `.claude/rules/reference/architecture.md` — Architecture Principles +- `.claude/rules/reference/augmented-coding-patterns.md` — Augmented Coding Patterns +- `.claude/rules/reference/coding-style.md` — Coding Style +- `.claude/rules/reference/context-layering.md` — The four context layers an agent reads, and the one-fact-one-layer rule that keeps AGENTS.md thin and free of conflict with memory. +- `.claude/rules/reference/development-workflow.md` — Development Workflow +- `.claude/rules/reference/git-workflow.md` — Git Workflow +- `.claude/rules/reference/hooks.md` — Hooks System +- `.claude/rules/reference/patterns.md` — Common Patterns +- `.claude/rules/reference/performance.md` — Performance Optimization +- `.claude/rules/reference/security.md` — Security Guidelines +- `.claude/rules/reference/skill-management.md` — Discover, vet, and expose agent skills on demand with skillager, so the right skills are available per task without loading every skill into every chat. +- `.claude/rules/reference/task-management.md` — Track multi-step agent work in a durable, dependency-aware task store; prefer the lightest non-invasive backend (SQLite + JSONL) and only add heavier sync when you actually need it. +- `.claude/rules/reference/testing.md` — Testing Requirements ### go diff --git a/targets/claude/skills/review/SKILL.md b/targets/claude/skills/review/SKILL.md index c0f48f7..786d065 100644 --- a/targets/claude/skills/review/SKILL.md +++ b/targets/claude/skills/review/SKILL.md @@ -32,7 +32,7 @@ Hacky patterns to flag: - **Stringly-typed code**: raw strings where constants, enums, or branded types already exist - **Unnecessary comments**: comments narrating what the code does (well-named identifiers already do that) or referencing the task, keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds) - **Boundary violations**: directories or modules with architectural rules (search for `boundary_test.go`, `arch-test`, ESLint `no-restricted-imports`, etc.) that the change might violate -- **Slop & erosion** (`rules/common/anti-slop.md`): single-implementer interfaces / single-entry registries / factories returning a constant (overengineering), caching of constants or parallelism for tiny collections (premature optimization), narration comments and echo docstrings (documentation noise), success-booleans / generic error messages / retries that swallow failures (error obscuring), silent fallbacks and auto-correction (hidden behavior), and unrequested features or no-op validation (spec deviation). Weight toward code that **extends** an existing module — apply the erosion test: _would this look like this if written from scratch with today's requirements?_ +- **Slop & erosion** (`rules/reference/anti-slop.md`): single-implementer interfaces / single-entry registries / factories returning a constant (overengineering), caching of constants or parallelism for tiny collections (premature optimization), narration comments and echo docstrings (documentation noise), success-booleans / generic error messages / retries that swallow failures (error obscuring), silent fallbacks and auto-correction (hidden behavior), and unrequested features or no-op validation (spec deviation). Weight toward code that **extends** an existing module — apply the erosion test: _would this look like this if written from scratch with today's requirements?_ ### Agent 3: Efficiency (general-purpose) diff --git a/targets/claude/skills/slop-check/SKILL.md b/targets/claude/skills/slop-check/SKILL.md index 7f4dd9e..f67d2d7 100644 --- a/targets/claude/skills/slop-check/SKILL.md +++ b/targets/claude/skills/slop-check/SKILL.md @@ -29,7 +29,7 @@ For the extended surface, **read the whole enclosing function/module**, not just ## Phase 2: Judge against the rubric (the model judges, not regex) -The rubric is the catalog in the `anti-slop` rule (`rules/common/anti-slop.md`, the SlopCodeBench 45-criterion judge, grouped). These are **semantic** judgments — do not grep for them; read and reason. For a large or cross-file diff, dispatch a general-purpose reviewer with a role clamp ("You are a verification agent; you did NOT write this code; actively read the enclosing modules") and the anti-slop catalog; otherwise judge directly. +The rubric is the catalog in the `anti-slop` rule (`rules/reference/anti-slop.md`, the SlopCodeBench 45-criterion judge, grouped). These are **semantic** judgments — do not grep for them; read and reason. For a large or cross-file diff, dispatch a general-purpose reviewer with a role clamp ("You are a verification agent; you did NOT write this code; actively read the enclosing modules") and the anti-slop catalog; otherwise judge directly. For each touched region, walk the catalog groups and record concrete hits with `file:line`: diff --git a/targets/codex/AGENTS.md b/targets/codex/AGENTS.md index 2a7b2ef..c207dfa 100644 --- a/targets/codex/AGENTS.md +++ b/targets/codex/AGENTS.md @@ -20,6 +20,7 @@ Each is a section (matched by heading) in `AGENTS.full.md`: - **Context Layering** (`common/context-layering.md`) — The four context layers an agent reads, and the one-fact-one-layer rule that keeps AGENTS.md thin and free of conflict with memory. - **Development Workflow** (`common/development-workflow.md`) - **Git Workflow** (`common/git-workflow.md`) +- **House Rules (always-on)** (`common/house-rules.md`) — Always-on essentials — autonomy boundary, output discipline, coding/architecture/security standards, ZFC, anti-slop trigger. Detailed catalogs are in rules/reference/ (on-demand). - **Common Patterns** (`common/patterns.md`) - **Performance Optimization** (`common/performance.md`) - **Security Guidelines** (`common/security.md`) diff --git a/targets/codex/agents/architect.md b/targets/codex/agents/architect.md index 2d42eff..c97a874 100644 --- a/targets/codex/agents/architect.md +++ b/targets/codex/agents/architect.md @@ -44,7 +44,7 @@ For each design decision, document: ## Architectural Principles -> Global standards live in `~/.claude/rules/common/architecture.md`. Every design proposal must pass those rules: SRP, clear contracts, layering (no upward deps), statelessness, observability, no swallowed errors, no race conditions, async-over-polling, KISS/YAGNI, first-principles fit. +> Global standards live in `~/.claude/rules/reference/architecture.md`. Every design proposal must pass those rules: SRP, clear contracts, layering (no upward deps), statelessness, observability, no swallowed errors, no race conditions, async-over-polling, KISS/YAGNI, first-principles fit. ### 1. Modularity & Separation of Concerns diff --git a/targets/codex/agents/code-reviewer.md b/targets/codex/agents/code-reviewer.md index 5a9f402..879bdd0 100644 --- a/targets/codex/agents/code-reviewer.md +++ b/targets/codex/agents/code-reviewer.md @@ -166,7 +166,7 @@ const usersWithPosts = await db.query(` ### Architecture Principles (HIGH) -Check against `~/.claude/rules/common/architecture.md`: +Check against `~/.claude/rules/reference/architecture.md`: - **SRP violations**: Modules with multiple reasons to change; classes named "Manager"/"Helper"/"Util" that accumulate unrelated methods - **Layering violations**: Upward dependencies (lower layer importing from a higher one), presentation logic in data layer, business rules leaking into controllers @@ -182,7 +182,7 @@ Check against `~/.claude/rules/common/architecture.md`: ### AI Slop & Erosion (HIGH) -Check against `~/.claude/rules/common/anti-slop.md`. These are the patterns AI-generated and iteratively-extended code accumulates — weight your attention toward code that **extends** an existing function/module rather than greenfield additions: +Check against `~/.claude/rules/reference/anti-slop.md`. These are the patterns AI-generated and iteratively-extended code accumulates — weight your attention toward code that **extends** an existing function/module rather than greenfield additions: - **Documentation noise**: narration comments ("Step 1:"), docstrings that restate the function name, entry/exit logging in short functions - **Overengineering**: single-implementer interfaces, single-entry registries, factories that return a constant, strategies set once and never varied, primitive/monadic wrappers with no behavior @@ -260,7 +260,7 @@ When reviewing AI-generated changes, prioritize: 2. Security assumptions and trust boundaries 3. Hidden coupling or accidental architecture drift 4. Unnecessary model-cost-inducing complexity -5. Slop and erosion signatures — run the **AI Slop & Erosion** checklist above (`~/.claude/rules/common/anti-slop.md`). AI-extended code is the highest-yield surface for the overengineering, documentation-noise, and error-obscuring patterns. +5. Slop and erosion signatures — run the **AI Slop & Erosion** checklist above (`~/.claude/rules/reference/anti-slop.md`). AI-extended code is the highest-yield surface for the overengineering, documentation-noise, and error-obscuring patterns. Cost-awareness check: diff --git a/targets/codex/agents/tdd-guide.md b/targets/codex/agents/tdd-guide.md index 0e6998f..24ccf4d 100644 --- a/targets/codex/agents/tdd-guide.md +++ b/targets/codex/agents/tdd-guide.md @@ -1,6 +1,6 @@ You are a Test-Driven Development (TDD) specialist who ensures all code is developed test-first with comprehensive coverage. -> TDD alignment: `~/.claude/rules/common/architecture.md` treats "hard to test" as a design smell, not a test-writing problem. If a component resists unit or integration testing, flag it for redesign, don't pile on mocks to force coverage. Observability (logging/metrics/tracing) is part of testability; build it in from the first RED-GREEN cycle. +> TDD alignment: `~/.claude/rules/reference/architecture.md` treats "hard to test" as a design smell, not a test-writing problem. If a component resists unit or integration testing, flag it for redesign, don't pile on mocks to force coverage. Observability (logging/metrics/tracing) is part of testability; build it in from the first RED-GREEN cycle. ## Your Role diff --git a/targets/codex/prompts/code-review.md b/targets/codex/prompts/code-review.md index 304ae47..a4bf55e 100644 --- a/targets/codex/prompts/code-review.md +++ b/targets/codex/prompts/code-review.md @@ -25,7 +25,7 @@ Comprehensive security and quality review of uncommitted changes: - TODO/FIXME comments - Missing JSDoc for public APIs -**AI Slop & Erosion (HIGH)** — see the `anti-slop` rule (`rules/common/anti-slop.md`), weight toward code that extends existing modules: +**AI Slop & Erosion (HIGH)** — see the `anti-slop` rule (`rules/reference/anti-slop.md`), weight toward code that extends existing modules: - Overengineering: single-implementer interfaces, single-entry registries, factories returning a constant - Documentation noise: narration comments, docstrings that restate the function name diff --git a/targets/codex/prompts/slop-check.md b/targets/codex/prompts/slop-check.md index 3974701..4b3d7d1 100644 --- a/targets/codex/prompts/slop-check.md +++ b/targets/codex/prompts/slop-check.md @@ -24,7 +24,7 @@ For the extended surface, **read the whole enclosing function/module**, not just ## Phase 2: Judge against the rubric (the model judges, not regex) -The rubric is the catalog in the `anti-slop` rule (`rules/common/anti-slop.md`, the SlopCodeBench 45-criterion judge, grouped). These are **semantic** judgments — do not grep for them; read and reason. For a large or cross-file diff, dispatch a general-purpose reviewer with a role clamp ("You are a verification agent; you did NOT write this code; actively read the enclosing modules") and the anti-slop catalog; otherwise judge directly. +The rubric is the catalog in the `anti-slop` rule (`rules/reference/anti-slop.md`, the SlopCodeBench 45-criterion judge, grouped). These are **semantic** judgments — do not grep for them; read and reason. For a large or cross-file diff, dispatch a general-purpose reviewer with a role clamp ("You are a verification agent; you did NOT write this code; actively read the enclosing modules") and the anti-slop catalog; otherwise judge directly. For each touched region, walk the catalog groups and record concrete hits with `file:line`: