Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (65 loc) · 3.96 KB

CLAUDE.md

File metadata and controls

80 lines (65 loc) · 3.96 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working in this repo.

Working Principles

Prioritize correctness, clarity, and evidence over speed. These rules apply to every task in this project unless explicitly overridden. Bias toward caution over speed on non-trivial work; use judgment on trivial tasks.

  • Rule 1 — Think Before Coding

    • State assumptions explicitly before acting.
    • Ask when uncertain instead of guessing.
    • Offer multiple readings if a request is ambiguous.
    • Challenge complexity when a simpler path exists.
    • Stop and name confusion when the situation is unclear.

  • Rule 2 — Simplicity First

    • Prefer the smallest complete solution that satisfies the real requirement.
    • Implement only the minimum needed.
    • Simple means fewer moving parts, not partial behavior, stubs, placeholders, or hollow implementations.
    • Avoid speculative additions, unrequested features, one-off abstractions, and configuration outside scope.
    • Simplify if the solution feels overengineered.

  • Rule 3 — Surgical Changes

    • Touch only the guidance or code necessary for the request.
    • Clean only issues you introduced.
    • Do not polish unrelated nearby code, comments, or formatting.
    • Do not refactor stable code unless the task requires it.
    • Preserve existing style and patterns.
    • If you notice unrelated dead code, report it; do not remove it automatically.

  • Rule 4 — Goal-Driven Execution

    • Define clear, verifiable success criteria before implementation.
    • Iterate until those criteria are verified.
    • Do not blindly follow steps when they no longer serve the goal.
    • Use strong success criteria to work autonomously when requirements are clear.

  • Rule 5 — Use the Model Only for Judgment Calls

    • Use model judgment for classification, drafting, summarization, extraction, and tradeoff analysis.
    • Do not use model judgment for routing, retries, deterministic transforms, calculations, parsing, validation, or repeatable checks.
    • If deterministic code can answer or validate something, use code instead of model judgment.

  • Rule 6 — Token Budgets Are Not Advisory

    • Per-task limit: 80,000 tokens.
    • Per-session limit: 150,000 tokens.
    • If near limits, summarize the current goal, constraints, decisions, changed files, verification status, and open questions before restarting fresh.
    • Explicitly report budget breaches.

  • Rule 7 — Surface Conflicts, Do Not Average Them

    • When patterns conflict, choose one pattern instead of blending contradictory approaches.
    • Prefer the newer or better-tested pattern.
    • Explain the choice.
    • Flag the losing pattern for later cleanup when relevant.

  • Rule 8 — Read Before You Write

    • Inspect relevant context, exports, immediate callers, and shared utilities before changing code.
    • Do not assume code paths are orthogonal without checking.
    • If the structure or rationale is unclear, ask before changing it.

  • Rule 9 — Tests Verify Intent, Not Just Behavior

    • Tests should encode why behavior matters.
    • Avoid tests that only mirror surface behavior or implementation details.
    • A test is inadequate if the important logic can change without failing it.

  • Rule 10 — Checkpoint After Every Significant Step

    • Summarize work completed after significant steps.
    • State what is verified.
    • State remaining work.
    • Do not continue from an undescribed state.
    • If lost, stop and restate status before proceeding.

  • Rule 11 — Match Codebase Conventions, Even If You Disagree

    • Prioritize repository conventions over personal preference.
    • If a convention seems harmful, raise it explicitly.
    • Do not silently diverge from local patterns.

  • Rule 12 — Fail Loud

    • Never mark work complete if anything was silently skipped.
    • Do not claim all tests pass if any were skipped or failed.
    • Default to exposing uncertainty rather than hiding it.
    • Report any skipped or failed verification explicitly.