Skip to content

CLAUDE.md

Latest commit

 

History

History
109 lines (85 loc) · 9.18 KB

CLAUDE.md

File metadata and controls

109 lines (85 loc) · 9.18 KB

Project Rules

  • Always communicate and work in English.
  • Before starting development, check if PRD.md exists in the project root. If it does, read and follow the requirements defined in it throughout the development process.
  • IMPORTANT: Follow Test-Driven Development (TDD). See the Testing (TDD) section below for detailed rules.
  • IMPORTANT: Read and follow METHODOLOGY.md before starting any task.
  • When editing CLAUDE.md, use the minimum words and sentences needed to convey 100% of the meaning.
  • Before each commit, run auto-formatting. Follow FORMATTING.md first; if it has no command, use the project's existing formatter; if none exists, use the language-default formatter and record the exact command in FORMATTING.md.
  • After completing each planned task, run tests and commit before moving to the next task. Skip tests if the change has no impact on runtime behavior (e.g., docs, comments, CI config). Changes to runtime config files (YAML, JSON, etc. read by code) must still trigger tests.
  • After any code change (feature addition, bug fix, refactoring, PR merge), check if README.md needs updating. If project description, usage, setup, architecture, or API changed, update README.md with clear, concise language. Keep it minimal — only document what users need to know.

Testing (TDD)

  • Write tests first. Follow Red-Green-Refactor: (1) failing test, (2) minimal code to pass, (3) refactor.
  • Use real-world scenarios and realistic data in tests. Prefer actual use cases over trivial/contrived examples.
  • Never overfit to tests. Implementation must solve the general problem, not just the specific test cases. No hardcoded returns, no input-matching conditionals, no logic that only handles test values. Use triangulation — when a fake/hardcoded implementation passes, add tests with different inputs to force generalization.
  • Test behavior, not implementation. Assert on observable outcomes, not internal details — tests must survive refactoring.
  • Every new feature or bug fix must have corresponding tests.
  • Optimize test execution speed. Run independent tests in parallel (multi-process/multi-thread, async, or parallel runner). Use the framework's built-in parallel execution (e.g., pytest-xdist, jest --workers, go test -parallel). Keep each test isolated — no shared mutable state — so parallel execution is safe.
  • For I/O-bound tests (network, file, DB), prefer async or use mocks to avoid blocking. For CPU-bound tests, use multi-process/multi-thread parallelism.
  • If full test suite exceeds 30 seconds, investigate: split slow integration tests from fast unit tests, run unit tests first for quick feedback.
  • Skip tests when no runtime impact. In CI/CD, use path filters to trigger tests only when source code, test files, or runtime config files (YAML, JSON, etc. read by code) are modified. Non-runtime changes (docs, README, .md, CI pipeline config) should not trigger test runs. Locally, verify whether a change affects runtime behavior before running tests.

PDF Fidelity

  • For Markdown/HTML/PDF rendering work, do not rely on manual inspection alone. Add or run automated fidelity checks.
  • Maintain a real-world validation corpus of about 50 popular public GitHub repos with diverse README patterns.
  • Prefer automated visual and structural checks that catch clipping, truncation, missing images, missing text, broken tables, and page-loss regressions.
  • Fidelity target is content preservation, not pixel-perfect browser parity. If an interactive browser pattern does not map to PDF, transform it into a print-safe layout that still shows all content, such as wrapping, stacking, expanding, or paginating.
  • Do not assume a behavior is impossible and choose an easier degraded output without first testing whether a print-safe implementation is feasible.
  • When a corpus document reveals a fidelity bug, add a regression fixture or test for that pattern before fixing it.

Logging

  • Add structured logs at key decision points, state transitions, and external calls — not every line. Logs alone should reveal the execution flow and root cause.
  • Include context: request/correlation IDs, input parameters, elapsed time, and outcome (success/failure with reason).
  • Use appropriate log levels: ERROR for failures requiring action, WARN for recoverable issues, INFO for business events, DEBUG for development diagnostics.
  • Keep logging thread-safe. Use thread/coroutine IDs in log context for multi-threaded environments.
  • Never log sensitive data (credentials, tokens, PII). Mask or omit them.
  • Avoid excessive logging in hot paths — logging must not degrade performance or increase latency noticeably.

Naming

  • Names must be self-descriptive — understandable without reading surrounding code. Avoid cryptic abbreviations (proc, mgr, tmp).
  • Prefer clarity over brevity, but don't over-pad. user_email > e, calculate_shipping_cost > calc — but no need for calculate_the_total_shipping_cost_for_user.
  • Booleans should read as yes/no questions: is_valid, has_permission, should_retry.
  • Functions/methods should describe the action and target: parse_config, send_notification, validate_input.

Types

  • Prefer explicit type annotations over type inference. Implicit types (auto, untyped Python, any) force readers to infer from context, increasing ambiguity.
  • At minimum, annotate function signatures (parameters and return types). Annotate variables when the type isn't obvious from the assigned value.

Comments

  • Explain why, not what. Code already shows what it does — comments should capture intent, constraints, and non-obvious decisions.
  • Comment business rules, workarounds, and "why this approach over the obvious one" — context that can't be inferred from code alone.
  • Mark known limitations with TODO(reason) or FIXME(reason) — always include why, not just what.
  • Delete comments when the code changes — outdated comments are worse than no comments.

Reference Projects

  • First check references/INDEX.md if it exists whenever the task includes at least one of the following:
    • adding a new feature
    • changing runtime behavior
    • changing public CLI or API behavior
    • introducing a new dependency
    • modifying code in more than one module or crate
    • making an architectural or data model decision
  • Read only the single most relevant reference file unless more are clearly necessary.
  • If no relevant project exists in references/ for a task above, search for a well-maintained open-source project that solves a similar problem. Search across languages when useful. Evaluate by maintenance activity and architectural similarity.
  • Add each useful new reference to references/INDEX.md and create a matching detail file in references/. Keep detail files under 50 lines.
  • Skip this step for documentation-only edits, formatting-only edits, comments-only edits, renames without behavior changes, and isolated test-only changes that do not require new design decisions.
  • Cite the reference project that informed the implementation when applying its patterns.

Git Configuration

  • All commits must use the local git config user.name and user.email. Verify with git config user.name and git config user.email before committing.
  • All commits must include Signed-off-by line (always use git commit -s). The Signed-off-by name must match the commit author.

Branching & PR Workflow

  • All changes go through pull requests. No direct commits to main.
  • Branch naming: <type>/<short-description> (e.g., feat/add-parser, fix/table-bug).
  • One branch = one focused unit of work.
  • Use git worktrees for all branch work. Do not use git checkout/git switch in the main repo.
    • Create: git worktree add ../<repo-name>-<branch-name> -b <type>/<short-description>
    • Work and push from inside the worktree.
    • Do not delete worktrees immediately after task completion — remove only when starting new work or upon user confirmation.

PR Merge Procedure

Follow all steps in order:

  1. Rewrite PR description if empty/unclear via gh pr edit. Include: what changed, why, key changes, and relevant context.
  2. Cross-reference related issues (gh issue list). Use "Related: #N" — avoid auto-close keywords unless instructed.
  3. Check for conflicts. If main has advanced, rebase/merge as needed.
  4. Wait for CI to pass: gh pr checks <number> --watch. Abort if tests fail.
  5. Final code review via gh pr diff <number> — check for debug statements, hardcoded paths, credentials, unused imports.
  6. Merge: gh pr merge <number> --merge. Never use --delete-branch (worktree depends on the branch).
  7. Return to main repo, git pull to sync.
  8. Remove worktree: git worktree remove ../<repo-name>-<branch-name>
  9. Delete local branch: git branch -d <branch-name>
  10. Delete remote branch: git push origin --delete <branch-name>

Releases

  • When creating a GitHub Release, include a Contributors section crediting all external contributors since the previous release.
  • Use git log <prev-tag>..HEAD --format='%an' | sort -u to find contributors. List each with their GitHub profile link and a brief summary of their contribution.