Skip to content

feat: add global CLAUDE.md for TDD #15

@scc-tw

Description

@scc-tw

Summary

Introduce a global CLAUDE.md at the repository root to standardise how we collaborate with LLM pair‑programmers (e.g. Claude) using Test‑Driven Development (TDD) and Kent Beck’s Tidy First

Context & Rationale

  • Proven template – Kent Beck’s BPlusTree3 project ships a concise CLAUDE.md that drives an automated Red → Green → Refactor workflow for every change.
  • Enforces canonical TDD cycle – centralising the rules keeps every contributor (human or AI) on the same page about writing the failing test first, making it pass, then refactoring.
  • Separates structure from behaviour – Tidy First insists we commit structural tidies separately from behavioural changes, reducing review burden and merge conflicts.
  • Small, frequent commits – numerous case‑studies show that tight Red‑Green loops plus micro‑tidies accelerate delivery and cut rollback cost.
  • Scales across monorepo – a single root‑level file avoids duplicated instructions inside each package or service.

Proposal

  1. Copy & adapt rust/docs/CLAUDE.md (§Role, Core Principles, Commit Discipline). Keep wording but replace examples with our language‑specific conventions.
  2. Place the new file at /<repo‑root>/CLAUDE.md.
  3. Amend CONTRIBUTING.md to reference the file.
  4. Add a CI guard (simple grep or markdown‑lint rule) that fails if the file is removed or edited without running make test.

Acceptance Criteria

  • CLAUDE.md exists in the repository root and renders without lint warnings.
  • CI pipeline fails when a PR violates any Commit Discipline bullet (e.g., structural + behavioural change in same commit).
  • A link to CLAUDE.md appears in Contributing guidelines.
  • At least one green‑to‑red‑to‑refactor demonstration PR merged using the new workflow.

Tasks

  • Draft CLAUDE.md (copy → adapt wording → PR)
  • Update CONTRIBUTING.md with a “Working with Claude” subsection
  • Implement CI check (bash / pre‑commit)
  • Showcase example PR proving the loop
  • Announce the change in #dev‑announce

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions