feat: 決定論的ロジック層への TDD ハーネスを導入

[yusuke0610]

Summary

• 決定論的ビジネスロジック層（mutmut/stryker のミューテーションテスト対象と同一スコープ）の実装変更を TDD（red → green → refactor） で行う方針を導入（ADR-0019）
• ワークフロー正本 .claude/rules/common/tdd.md（backend/web 編集時に自動ロード）を新設し、既存の backend/test.md / web/test.md / CLAUDE.md から誘導
• 機械ゲート scripts/lint-tdd.sh（make lint-tdd）を新設。TDD 対象の実装変更にテスト差分が随伴しているかを検証し、make lint / make ci および CI（test.yml の test-backend ジョブ）に組み込み。振る舞いを変えない変更は Tdd-Exempt: <理由> コミットトレーラーで除外可能
• AI 向け段階制御スキル /tdd（.claude/skills/tdd/SKILL.md）を新設。対象判定 → テスト設計提示 → red（失敗確認）→ green → refactor の各フェーズで停止・報告する
• docs/development.md / CONTRIBUTING.md に人間向けの概説を追記、docs/adr/README.md / docs/design-principles.md の索引を更新

設計判断

• TDD 適用スコープは新規リストを作らず、既存の mutation 設定（backend/pyproject.toml の [tool.mutmut] only_mutate / web/stryker.conf.json の mutate）を SSoT として共有（ADR-0017 と対になる事前プロセス）
• 機械ゲートは「テストファーストの証明」ではなく「テスト差分の随伴」という検証可能な必要条件に限定（限界は ADR-0019 に明記）

Test plan

• make lint-adr-index green（ADR 索引の drift なし）
• make lint-tdd の動作確認: 対象ファイルのみ変更→fail / テスト随伴→pass / Tdd-Exempt トレーラー→skip / TDD_EXEMPT=1→skip / stryker 除外パターン（pdfjs.ts）→対象外
• make ci（lint + backend pytest + web vitest 365 件 + build）green
• ドキュメント・スクリプト変更のみで backend/web の実行時挙動に影響しないため E2E・smoke は対象外。CI 上で test.yml の新ステップが期待どおり動くことは本 PR の CI 結果で確認する

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a standardized TDD workflow for deterministic logic changes, including red → green → refactor guidance and an exemption path for behavior-only edits.
  • Added a new lint check to verify test coverage stays aligned with implementation changes.
• Documentation
  • Updated development and contributing guidance to explain when the TDD workflow applies and how to validate it.
  • Expanded architecture and design-principles docs to reflect the new quality process.

[coderabbitai]

Warning

Review limit reached

@yusuke0610, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 22 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 22cbd120-2bdc-4f14-b87d-4868259a0028

📥 Commits

Reviewing files that changed from the base of the PR and between ff27798 and 9501a1d.

📒 Files selected for processing (2)

• docs/adr/README.md
• docs/design-principles.md

📝 Walkthrough

Walkthrough

This PR introduces ADR-0019 to mandate test-driven development (red→green→refactor) for changes to deterministic logic layers identified via mutmut (backend) and Stryker (web) mutation-test configurations. It adds a lint-tdd.sh enforcement script wired into make lint/CI, new rule/skill docs, and updates supporting documentation.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Changes

TDD Gate Introduction

Layer / File(s)	Summary
ADR-0019 decision document docs/adr/0019-tdd-for-logic-layer.md	Adds ADR defining TDD scope (reusing ADR-0017 mutation targets), workflow, make lint-tdd gate, Tdd-Exempt mechanism, trade-offs, and links to design principles.
TDD rule and skill documents .claude/rules/common/tdd.md, .claude/rules/backend/test.md, .claude/rules/web/test.md, .claude/skills/tdd/SKILL.md	Adds common TDD workflow rule, scope-determination sections in backend/web test rules, and a phase-based TDD skill document.
lint-tdd.sh enforcement script scripts/lint-tdd.sh	Adds a script that resolves base ref, honors Tdd-Exempt/TDD_EXEMPT, parses mutmut/Stryker globs, classifies changed files, and fails when matched implementation changes lack test diffs.
Makefile and CI wiring Makefile, .github/workflows/test.yml	Adds lint-tdd target wired into lint/help output; CI checkout now uses fetch-depth: 0 and runs a new "Lint SSoT" step invoking the script.
Documentation and agent instruction updates .claude/CLAUDE.md, CONTRIBUTING.md, docs/development.md, docs/design-principles.md, docs/adr/README.md	Updates commit/PR flow, contributing guide, development docs, principle matrix, and ADR index to reference ADR-0019 and the TDD gate.

Sequence Diagram(s)

sequenceDiagram
  participant CI as CI Workflow
  participant Script as lint-tdd.sh
  participant Git as Git

  CI->>Script: bash scripts/lint-tdd.sh
  Script->>Git: resolve base ref / merge-base
  Script->>Script: check Tdd-Exempt trailer or TDD_EXEMPT=1
  alt exempt
    Script-->>CI: exit 0 (skip)
  else not exempt
    Script->>Git: diff changed files vs base
    Script->>Script: parse mutmut/stryker globs
    Script->>Script: classify impl vs test file changes
    alt missing test diff for matched impl
      Script-->>CI: ERROR + exit 1
    else
      Script-->>CI: OK + exit 0
    end
  end

Loading

Possibly related PRs

• yusuke0610/devforge#297: Both PRs update .claude/CLAUDE.md's commit/PR flow "stage" instructions.
• yusuke0610/devforge#398: Both PRs update .claude/CLAUDE.md's commit/PR workflow documentation without overlapping on the TDD gate logic.
• yusuke0610/devforge#450: Introduces/adjusts backend/pyproject.toml mutmut and web/stryker.conf.json mutation configs that this PR's lint-tdd.sh and TDD rules directly reference.

Suggested labels: documentation, feature, test, agent, ci

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: introducing a TDD harness for deterministic logic-layer changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/tdd-harness

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}