Add ~/.claude/rules/ workflow files to chezmoi
planning.md, execution.md, quality.md — the agent workflow rules loaded into every session via ~/.claude/rules/. Previously untracked locally. planning.md now includes an "For infra changes" subsection directing researchers to infra/docs/architecture/ and infra/docs/runbooks/ before dispatching researcher subagents. execution.md now includes §7 "Docs — keep infra/docs/ current" covering doc upkeep for architecture-visible changes and new operational procedures. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Viktor Barzin
parent
eb19c1c27d
commit
7bbe203578
3 changed files with 330 additions and 0 deletions
117
dot_claude/rules/execution.md
Normal file
117
dot_claude/rules/execution.md
Normal file
|
|
@ -0,0 +1,117 @@
|
|||
# Execution (applies to ALL agents)
|
||||
|
||||
Once a plan is approved (via ExitPlanMode or explicit user go-ahead), execute end-to-end. This file governs what happens AFTER planning — see `planning.md` for the interview/research/challenger flow that precedes it.
|
||||
|
||||
## 1. Default posture — run through, no mid-task gates
|
||||
|
||||
**Keep working until the user's request is satisfied.**
|
||||
|
||||
- Don't stop after research, after a single commit, after each "phase" or "batch" — keep going.
|
||||
- No "Should I proceed with X?" / "Want me to continue?" prompts between steps of an approved plan.
|
||||
- No mid-task checkpoints or batch approvals. The user interrupts if something drifts.
|
||||
- Course-correct on user interruption, not by polling.
|
||||
|
||||
Stopping is the exception that needs a reason. The ONLY reasons to stop mid-execution are listed in §2.
|
||||
|
||||
## 2. When to stop and ask (the ONLY ASK FIRST list)
|
||||
|
||||
Pause and surface to the user (or, if you're a subagent, to the session that spawned you) for:
|
||||
|
||||
- **Destructive ops** — force-push, `git reset --hard`, `rm -rf`, dropping DB tables, killing processes the user didn't start
|
||||
- **Schema / public API changes** — REST, GraphQL, gRPC, DB schema
|
||||
- **Deleting tested code** — anything that has tests covering it
|
||||
- **Interface / contract changes** that affect other teams
|
||||
- **Live network devices** — routers, switches, firewalls (confirmed preference)
|
||||
- **Scope changes** — work beyond the approved plan
|
||||
- **New genuine ambiguity** discovered mid-execution that the research didn't resolve
|
||||
- **Configuration changes with external impact** — credentials, DNS, firewall rules, production configs
|
||||
|
||||
Anything NOT on this list → just do it. Don't invent new reasons to pause.
|
||||
|
||||
## 3. Push / merge behaviour
|
||||
|
||||
On personal repositories (this monorepo and similar):
|
||||
|
||||
- **Push after every commit** — don't batch, don't wait for approval
|
||||
- **Direct to master** — no feature branches, no PRs unless the user explicitly asks
|
||||
- **Wait for CI / deployment** to complete before marking the task done — a green local build isn't the finish line if CI still runs
|
||||
- **`git add` specific files by name** — never `git add -A` or `git add .`, which can sweep in secrets, worktree cruft, or untracked experiments
|
||||
- **Never skip hooks** (`--no-verify`, `--no-gpg-sign`) unless the user explicitly requests it
|
||||
- **Never force-push to master** — warn the user if they request it
|
||||
|
||||
Shared / corporate repos follow whatever PR flow the project uses; when in doubt, ask.
|
||||
|
||||
## 4. When to dispatch subagents
|
||||
|
||||
**Default: do the work inline.** The main session reads files, writes code, runs tests, commits. Every handoff costs clarity and context.
|
||||
|
||||
Spawn a subagent only when one of these is true:
|
||||
|
||||
- **Parallel independent work** — two or more genuinely independent investigations can run at the same time
|
||||
- **Context protection** — raw output would be huge (wide codebase sweeps, long log dumps, 50+ files) and would pollute the main context; let a subagent digest and summarise
|
||||
- **User asked** — the user explicitly requested an agent
|
||||
- **Long-running stand-alone task** — something that runs for a while and doesn't need your attention (use `run_in_background: true`)
|
||||
|
||||
### Dispatch table
|
||||
|
||||
| Task pattern | Agent type | Background? |
|
||||
|---|---|---|
|
||||
| Write code / fix code / refactor | `coder` | foreground |
|
||||
| Debug error / test failure | `debugger` | foreground |
|
||||
| Review code / plan scrutiny | `reviewer` | background |
|
||||
| Explore codebase / research | `researcher` | foreground |
|
||||
| System design / architecture | `architect` | foreground |
|
||||
| Run verification commands | `verifier` | foreground |
|
||||
|
||||
### Rules when you DO dispatch
|
||||
|
||||
1. **Parallel when independent** — 2+ independent subtasks = spawn agents in parallel in one message
|
||||
2. **Background for long-running** — agents marked "background" in the table use `run_in_background: true`
|
||||
3. **Context protection** — keep raw output inside the subagent; ask for a concise summary
|
||||
4. **Prompt quality** — every agent prompt MUST:
|
||||
- Be 50+ words
|
||||
- Start with a clear task description (action verbs: implement, fix, add, refactor)
|
||||
- Include acceptance criteria (checkboxes or "Done when" conditions)
|
||||
- Include specific file/path references
|
||||
5. **Failed agent recovery** — one retry with a refined prompt; second failure → escalate to the user with a summary
|
||||
|
||||
## 5. NEVER do these — no exceptions
|
||||
|
||||
- Create files without asking
|
||||
- Use `any` / untyped types when a specific type exists
|
||||
- Refactor adjacent code (only touch what's requested)
|
||||
- Add lint-ignore or type-error suppression comments
|
||||
- Edit generated / auto-generated files
|
||||
- Write implementation before tests (see `quality.md`)
|
||||
- Commit temp / one-off / test scripts to the repo — store them outside the repo instead
|
||||
|
||||
## 6. Before touching any directory
|
||||
|
||||
Check if it (or any parent up to repo root) contains project-specific rules (e.g., `.claude/CLAUDE.md`, `.cursor/rules`). If found, read those files first — they may override anything in this file.
|
||||
|
||||
## 7. Docs — keep `infra/docs/` current
|
||||
|
||||
For any infra change that alters state described in
|
||||
`infra/docs/architecture/` or `infra/docs/runbooks/`:
|
||||
|
||||
- **Update affected docs in the same commit.** Never land infra
|
||||
changes that leave docs stale.
|
||||
- **New architecture-visible component** (new service, storage class,
|
||||
module, integration) → add or extend the relevant
|
||||
`architecture/*.md` doc.
|
||||
- **New operational procedure** (restore flow, upgrade path, recovery
|
||||
step) → add a `runbooks/*.md` entry.
|
||||
- **Medium/large designed changes** — write a
|
||||
`plans/YYYY-MM-DD-<topic>-{design,plan}.md` pair while designing,
|
||||
not after.
|
||||
- **Incidents** → post-mortem in
|
||||
`post-mortems/YYYY-MM-DD-<topic>.md`.
|
||||
|
||||
If you can't tell which docs are affected, grep for the service or
|
||||
resource name across `infra/docs/` — treat every match as a candidate
|
||||
for update. This rule is `infra/`-scoped; other repos may or may not
|
||||
have `docs/` directories.
|
||||
|
||||
See also: `infra/.claude/CLAUDE.md` "Update docs with every change"
|
||||
for the full list of doc surfaces (includes `.claude/CLAUDE.md`,
|
||||
`AGENTS.md`, `.claude/reference/service-catalog.md`).
|
||||
141
dot_claude/rules/planning.md
Normal file
141
dot_claude/rules/planning.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
# Planning (applies to ALL agents)
|
||||
|
||||
**No implementation without completed research.** This flow MUST run before implementation begins.
|
||||
|
||||
The approval gate at the end of planning is **ExitPlanMode** — there is no second user-gate step once the plan is accepted. See `execution.md` for what happens after approval.
|
||||
|
||||
## Phase 1: Interview the User
|
||||
|
||||
**Interview relentlessly. Make sure that all ambiguities are resolved before execution.**
|
||||
|
||||
Before dispatching any researcher, ask targeted questions:
|
||||
|
||||
- **What exactly should change?** — not "add feature X" but the specific behavior expected
|
||||
- **What are the constraints?** — backward compatibility, performance requirements, scope limits
|
||||
- **What should NOT change?** — explicit out-of-scope items
|
||||
- **Who are the consumers?** — who calls this code, who depends on it, who will be affected
|
||||
- **What edge cases worry you?** — empty input, timeouts, stale data, concurrent access
|
||||
|
||||
**Gates — do NOT proceed to Phase 2 until ALL of these are true:**
|
||||
- [ ] Every question has been answered by the user (not assumed)
|
||||
- [ ] If any answer raised new questions, those were asked and answered too
|
||||
- [ ] Zero ambiguity remains — you can describe the exact change without "probably", "maybe", "might"
|
||||
- [ ] The user has not said "I'm not sure" about any critical decision — if they did, resolve it
|
||||
|
||||
**Longer planning = fewer fixes later.**
|
||||
|
||||
## Phase 2: Code Exploration
|
||||
|
||||
Dispatch `researcher` subagents:
|
||||
|
||||
### Mandatory investigations
|
||||
|
||||
| Investigation | How | Blocker if skipped |
|
||||
|---|---|---|
|
||||
| **All callers + blast radius** | Claude Code `Grep` tool for references, IDE "find all references" | Cannot assess risk of change |
|
||||
| **Existing patterns + reusable code** | Search for similar implementations before creating new | May duplicate existing utility |
|
||||
| **Edge cases + failure modes** | Trace error handling paths, check null/empty/stale input | Bugs ship to production |
|
||||
| **Current data state** | Query real data to understand current behavior with numbers | Assumptions may be wrong |
|
||||
|
||||
### For 2-3 parallel researchers
|
||||
|
||||
| Researcher | Focus |
|
||||
|---|---|
|
||||
| R1: Existing code + patterns | Trace the code path being modified. Find all callers. Identify existing abstractions to reuse. |
|
||||
| R2: Blast radius + dependencies | Who depends on this? Cross-team callers? What breaks if we change the interface? |
|
||||
| R3: Data + edge cases | Query real data to validate assumptions. Identify failure modes. |
|
||||
|
||||
### For infra changes
|
||||
|
||||
If the work touches state described in `infra/docs/architecture/` or
|
||||
`infra/docs/runbooks/`, read the relevant files BEFORE dispatching
|
||||
researchers. These docs are the authoritative starting point for
|
||||
current infra state — what's deployed, how it's wired, which
|
||||
conventions apply.
|
||||
|
||||
- `infra/docs/architecture/` — long-lived state (networking, storage,
|
||||
auth, databases, CI/CD, monitoring, backup-dr, etc.)
|
||||
- `infra/docs/runbooks/` — operational procedures (restores, upgrades,
|
||||
recoveries)
|
||||
- `infra/docs/plans/` — dated design/plan pairs for prior changes;
|
||||
grep here first when a similar change has been done before
|
||||
- `infra/docs/post-mortems/` — incident analyses; relevant when work
|
||||
touches a past failure surface
|
||||
|
||||
If the docs contradict the live state, that mismatch is itself a
|
||||
finding — surface it and resolve before proceeding.
|
||||
|
||||
## Phase 2b: Challenge, Verify, and Counter-Propose
|
||||
|
||||
**Always required.** After researchers report back, spawn **2 independent challenger subagents** in parallel. Each works INDEPENDENTLY — they do NOT see each other's output.
|
||||
|
||||
### Challenger mandate:
|
||||
|
||||
```
|
||||
## Role: Independent Research Challenger
|
||||
|
||||
You are reviewing research findings. Your job has THREE parts:
|
||||
|
||||
### 1. Scrutinize
|
||||
- Challenge the root cause analysis — what else could explain this?
|
||||
- Question assumptions — what is assumed without evidence?
|
||||
- Find missed edge cases — what happens with empty/null/stale/concurrent?
|
||||
- Identify missing investigations — what callers/consumers were NOT checked?
|
||||
|
||||
### 2. Verify every reference
|
||||
- For every FILE PATH cited: confirm it exists
|
||||
- For every FUNCTION/CLASS cited: confirm it exists
|
||||
- For every DATA CLAIM: confirm the data source exists and the query is valid
|
||||
- Flag ANY reference that cannot be verified as UNVERIFIED
|
||||
|
||||
### 3. Counter-propose
|
||||
- Propose at least ONE alternative approach to the problem
|
||||
- Your alternative must ALSO be backed by verified code/data references
|
||||
- Explain trade-offs: why your approach might be better or worse
|
||||
|
||||
Report:
|
||||
- VERIFIED: claims you confirmed exist
|
||||
- UNVERIFIED: claims you could not confirm
|
||||
- ISSUES: genuine problems with the findings (not nitpicks)
|
||||
- COUNTER-PROPOSAL: your alternative approach with references
|
||||
- VERDICT: AGREE (approach is sound) or DISAGREE (significant issues remain)
|
||||
```
|
||||
|
||||
### Convergence check
|
||||
|
||||
After challengers return, evaluate:
|
||||
|
||||
1. **Unverified claims** — if any reference was flagged UNVERIFIED, dispatch a researcher to verify or remove it
|
||||
2. **Genuine issues** — if challengers found real problems, dispatch a new research round → back to Phase 2b
|
||||
3. **Agreement** — if both challengers AGREE the approach is sound, proceed to Phase 3
|
||||
4. **Counter-proposals** — if a counter-proposal is clearly better, adopt it and re-validate
|
||||
|
||||
**Never present unvetted findings to the user.** All claims must be verified.
|
||||
|
||||
## Phase 3: Resolve All Ambiguities
|
||||
|
||||
After researchers report back AND challengers have agreed on the approach:
|
||||
|
||||
1. **List every open question** — anything the researchers couldn't answer or disagreed on
|
||||
2. **Ask the user** (via AskUserQuestion) to resolve each one — do NOT guess, do NOT assume
|
||||
3. **Present the plan via ExitPlanMode** with:
|
||||
- **Goal**: what we're doing and why
|
||||
- **Research Decisions**: callers, blast radius, patterns to reuse, edge cases
|
||||
- **Plan**: ordered steps with checkboxes
|
||||
|
||||
ExitPlanMode is the approval gate. Once the user accepts, hand off to `execution.md` — no further "should I proceed?" check.
|
||||
|
||||
## Research completeness checklist
|
||||
|
||||
Research is NOT complete if any of these are true:
|
||||
- [ ] Callers were not traced
|
||||
- [ ] No search for existing patterns
|
||||
- [ ] Edge cases not identified
|
||||
- [ ] Assumptions not validated with data
|
||||
- [ ] Open questions remain
|
||||
- [ ] No blast radius assessment
|
||||
- [ ] References not verified (file paths, functions cited without confirming they exist)
|
||||
- [ ] No challenge round completed
|
||||
- [ ] Challengers did not agree
|
||||
|
||||
If any box is checked, research is incomplete. Go back and fill the gaps before surfacing a plan.
|
||||
72
dot_claude/rules/quality.md
Normal file
72
dot_claude/rules/quality.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# Quality (applies to ALL agents)
|
||||
|
||||
**If you are writing code, this applies to YOU. No exceptions.**
|
||||
|
||||
## 1. TDD cycle — test-first
|
||||
|
||||
1. **RED** — Write a failing test. Run it. Confirm it fails.
|
||||
2. **GREEN** — Write minimal code to pass. Only enough to make the test green.
|
||||
3. **REFACTOR** — Clean up. Tests stay green.
|
||||
4. **VERIFY** — All must pass before committing:
|
||||
- Run tests: `pytest` (Python) / `npm test` (JS/TS)
|
||||
- Type check: `mypy .` (Python) / `tsc --noEmit` (TS)
|
||||
- Format: `yapf` (Python) / `prettier` (JS/TS)
|
||||
- Lint: `ruff check` (Python) / `eslint` (JS/TS) — **check the output**. Fix ALL errors before proceeding.
|
||||
5. **COMMIT** — commit the verified change.
|
||||
6. **REPEAT** — back to step 1.
|
||||
|
||||
## 2. Blockers — non-negotiable
|
||||
|
||||
- Writing implementation before a failing test exists = **BLOCKED**
|
||||
- Skipping tests (with any excuse) = **BLOCKED**
|
||||
- Writing tests after implementation = **BLOCKED**
|
||||
- Lint errors (unused variables, missing imports) = **BLOCKED** — run linter and fix before proceeding.
|
||||
|
||||
## 3. Test quality rules
|
||||
|
||||
- Each test verifies ONE behavior
|
||||
- Test behavior, not implementation (don't mock internals you own)
|
||||
- Use data providers / parameterized tests for multi-scenario coverage
|
||||
- Prefer property-based tests over example-based where the language supports it
|
||||
|
||||
## 4. Code quality checklist
|
||||
|
||||
Use this checklist for all code reviews and for your own output before committing. Evaluate each section and assign a verdict.
|
||||
|
||||
### AI slop detection
|
||||
|
||||
- [ ] No comments restating code (e.g., `// increment counter`, `// set the value`)
|
||||
- [ ] No unnecessary docstrings (e.g., `/** Gets the value */` on a getter)
|
||||
- [ ] No filler phrases (e.g., `This function is responsible for...`)
|
||||
- [ ] No wrapper functions adding no value
|
||||
- [ ] No commented-out code
|
||||
- [ ] No redundant type annotations in comments
|
||||
- [ ] No over-explained variable names — context comes from scope
|
||||
|
||||
### Engineering principles
|
||||
|
||||
- [ ] SRP: each function has a single responsibility (can describe without "and")
|
||||
- [ ] DRY: existing utilities reused (searched before creating new)
|
||||
- [ ] No premature abstractions or "just in case" parameters
|
||||
- [ ] Functions ≤20 lines (excluding type signatures)
|
||||
- [ ] Functions ≤3 parameters (more = use a struct/shape/object)
|
||||
- [ ] Functions ≤1 nesting level (early return over nested if/else)
|
||||
- [ ] No boolean parameters — named constants or enums instead
|
||||
- [ ] No magic values — named constants used
|
||||
- [ ] Error handling: fail fast, fail loud — no silent `catch {}`
|
||||
|
||||
### Idiomatic patterns
|
||||
|
||||
Write idiomatic code for each language. Common AI-generated anti-patterns:
|
||||
- [ ] Sequential awaits on independent calls → use concurrent/parallel execution
|
||||
- [ ] Loop + await → use async map/batch operations
|
||||
- [ ] Loading all data into memory then filtering → use server-side/query-level filtering
|
||||
- [ ] Acronyms in names (`ra`, `exp`) → use full names (`resource_account`, `experiment`)
|
||||
|
||||
### Verdicts
|
||||
|
||||
| Verdict | Criteria |
|
||||
|---------|----------|
|
||||
| **PASS** | All checks pass |
|
||||
| **REVISE** | Non-critical issues (naming, minor DRY, style nits) |
|
||||
| **BLOCK** | AI slop present, no tests for new behavior, or SOLID violation |
|
||||
Loading…
Add table
Add a link
Reference in a new issue