coder-rules

Coder Rules

5 CRITICAL Rules

• RULE_1 Plan Only: Implement ONLY what's in the plan. No improvements.
• RULE_2 Layer Dependency: NEVER violate {LAYER_RULE} (resolved from PROJECT-KNOWLEDGE.md; CLAUDE.md fallback). SKIP if slot unset OR {ARCHITECTURE_STYLE} != "layered".
• RULE_3 Clean Domain: NEVER add {DOMAIN_PROHIBIT} (resolved from PROJECT-KNOWLEDGE.md → DOMAIN_PROHIBIT; CLAUDE.md fallback) to domain entities. Tags belong in DTOs at the API/transport layer (your project's highest LAYERS entry per PROJECT-KNOWLEDGE.md → LAYERS). SKIP if slot unset.
• RULE_4 No Log+Return: NEVER log AND return error simultaneously.
• RULE_5 Tests Pass: Code NOT ready until tests pass.

Evaluate Protocol

Before implementation, critically evaluate plan (Phase 1.5):

• PROCEED: Plan is implementable as-is → start implementation
• REVISE: Minor gaps, can fix inline → note adjustments, proceed
• RETURN: Major gaps or feasibility issues → return to /plan-review with feedback

Evaluate checks: feasibility, hidden complexities, edge cases, performance, dependencies. Output: .claude/prompts/{feature}-evaluate.md

Evaluate has an exploration budget (SEE coder.md → evaluate_budget). When budget is reached, DECIDE with available information. Prefer PROCEED with notes over endless research. The planner already researched — evaluate is VALIDATION, not discovery.

Spec Check Protocol

After VERIFY passes, run spec compliance self-check (Phase 3.5):

• PASS: all Parts covered, scope respected, AC traceable → proceed to handoff
• PARTIAL: minor gaps documented → proceed with gaps noted in handoff
• FAIL: missing Part → inline fix (max 1 retry) → re-run VERIFY → re-check

Full checklist: Spec Check

Reviewer-side note: since release v1.21.x, code-reviewer applies an iter-≥2 spot-check on spec_check.status=PASS to guard against silent regressions. The coder is unaffected; the spot-check is performed entirely on the reviewer side via git diff --name-only.

Instructions

Step 1: Load plan and verify approval

Read .claude/prompts/{feature}.md. Verify plan passed plan-review. If plan not found → ERROR, exit. If not approved → ERROR, exit.

Step 2: Run Evaluate Protocol

Before writing ANY code, evaluate the plan critically. Decision: PROCEED / REVISE / RETURN (see Evaluate Protocol above). Write output to .claude/prompts/{feature}-evaluate.md.

Step 3: Implement parts in dependency order

Follow Parts order from plan. The plan's Parts list is the source of truth. If plan unordered: use {LAYERS} slot dependency direction when {ARCHITECTURE_STYLE} == "layered"; otherwise follow plan order verbatim and emit consolidated NIT if ambiguous. After each Part: PostToolUse hooks auto-format files (slot-driven via auto-fmt.sh: reads FMT_CMD and LANG_EXT from PROJECT-KNOWLEDGE.md cascade; supports {} placeholder for per-file mode). Run resolved {LINT_CMD} only for import/error checks. Check 5 CRITICAL Rules above continuously. Do NOT run FMT manually between Parts — hooks handle formatting, VERIFY handles final FMT+LINT. IMPORTANT: Do NOT run the FULL test suite (resolved {TEST_CMD}) between Parts — full verification runs ONCE at Step 4 VERIFY. Compile errors are caught by LINT; logic errors are caught at VERIFY. Targeted RED-GREEN-REFACTOR single-test runs within a Part are part of implementation (not verification) and are expected on every Part by default — see .claude/skills/tdd-rules/SKILL.md for the full cycle.

Step 4: Verify

Run full VERIFY using the resolved command from coder.md verify_startup cascade (PROJECT-KNOWLEDGE.md → VERIFY_CMD; CLAUDE.md fallback; DEPENDENCY_FILE-aware WARN; SKIP-with-NIT). Kit-default for Go projects (legacy CLAUDE.md fallback): go vet ./... && make fmt && make lint && make test. If tests fail 3x → load systematic-debugging skill, run Phase 1 root cause investigation. On success → proceed to Step 5.

Step 5: Spec Check and form handoff

Run SPEC CHECK (see Spec Check). S complexity: lightweight (coverage only). If FAIL: inline fix → re-run VERIFY → re-check (max 1 retry). On PASS/PARTIAL → form handoff payload for code-review, including spec_check.

Example

Clean Domain — no {DOMAIN_PROHIBIT} in entities (RULE_3)

Good:

type Service struct {
    ID string
}

Bad:

type Service struct {
    ID string `json:"id"`
}

Why: RULE_3 — Domain entities must be pure. No {DOMAIN_PROHIBIT} (resolved from PROJECT-KNOWLEDGE.md). Tags belong in DTOs at the API/transport layer (highest LAYERS entry per PROJECT-KNOWLEDGE.md → LAYERS).

For more examples, see Examples.

Common Issues

Tests fail 3x in a row — stuck

Cause: Bug in implementation logic or wrong approach. Fix: Load systematic-debugging skill. Run Phase 1 (Root Cause Investigation) with go test -v -count=1 ./... output as evidence. Trace data flow to find root cause. If root cause found → implement single fix + VERIFY. If still stuck → STOP, request manual help.

Layer-dependency violation detected

Cause: Didn't check architecture rules before implementation. Fix: Review layer-dependency rule per resolved {LAYER_RULE}. Refactor imports per the resolved rule. BLOCKER when slot is set AND {ARCHITECTURE_STYLE} == "layered"; SKIP-with-consolidated-NIT when unset/non-layered (canonical SKIP).

New library used without Context7

Cause: Assumed familiarity with library API. Fix: ALWAYS use Context7 for external dependencies: resolve-library-id → query-docs.

For all troubleshooting cases, see Troubleshooting.

Core Deps (loaded at startup)

• MCP Tools — Memory, Sequential Thinking, Context7 patterns and fallbacks

References

For detailed checks, read the supporting files in this skill directory:

• Examples — bad/good code patterns, layer import rules
• Checklist — self-verification at each coder phase
• Troubleshooting — common coder issues and fixes
• Review Response — handling CHANGES_REQUESTED feedback from code-reviewer (loaded on re-entry iterations)
• Spec Check — spec compliance self-check protocol (Phase 3.5, after VERIFY)
• code-researcher agent — available via Task tool for codebase investigation during evaluate phase (L/XL complexity)