👋

Claude Codeでチケット駆動開発をする（実装・レビュー）

に公開
Claude
Claude Code
tech

概要

自分が開発で使用しているチケット管理システムの実装とレビューのフェーズについて記載します。Claude Code向けです。

要件定義と設計については以下です。

https://zenn.dev/satonopan/articles/36d651bb6dcb1a

使用するコマンドとスキルは以下に置いています。

https://github.com/sato-dev1234/claude-code-sample/tree/v1.0

コマンド・スキル

ファイル構成

~/.claude/
├── commands/                   # コマンド定義
│   ├── tdd.md
│   └── comment-self-refine.md
└── skills/                     # スキル定義
    ├── managing-tickets/
    │   └── SKILL.md
    ├── implementing-tdd/
    │   └── SKILL.md
    ├── reviewing-code/
    │   └── SKILL.md
    ├── reviewing-test/
    │   └── SKILL.md
    ├── reviewing-flaky-patterns/
    │   └── SKILL.md
    ├── reviewing-assertion-quality/
    │   └── SKILL.md
    └── reviewing-comments/
        └── SKILL.md

使い方

TDD実装

Canon TDD（Red-Green-Refactor）サイクルで実装します。

/tdd

コメント品質改善

コメントをレビューし、自動修正します。

/comment-self-refine

各操作の詳細

TDD実装: /tdd

Canon TDD（Red-Green-Refactor）サイクルでテスト駆動開発を実施し、コードとテストの品質を自動改善します。要件定義・設計フェーズで作成したrequirements.mdやdesign.mdを読み込んで実装をします。

フロー

  1. 対象チケットの選択（managing-ticketsスキル） → TICKET_PATH
  2. <TICKET_PATH>/requirements.mdの読み込み → REQUIREMENTS
  3. <TICKET_PATH>/design.mdの読み込み → DESIGN
  4. REQUIREMENTSとDESIGNからテストリストを作成（依存関係情報付き） → TEST_LIST
  5. テスト数による実行方式の決定：
    • テスト数が5個未満：順次実行（implementing-tddスキル）
    • テスト数が5個以上：依存関係でグループ化して並列実行（最大5グループ、Task agent）
  6. <TICKET_PATH>/tasks.mdの完了項目を更新
  7. ベースブランチの決定 → BASE_BRANCH
  8. Exploreエージェントでgit diff <BASE_BRANCH>...HEADと変更ファイル内容を収集 → GATHERED_INFO
  9. Self-Refineループ（チェックリスト形式で実行）：
    - [ ] Review 1
- [ ] Fix 1 (skip if no issues)
- [ ] Review 2 (skip if Fix 1 skipped)
- [ ] Fix 2 (skip if no issues)
- [ ] Review 3 (skip if Fix 2 skipped)
- [ ] Fix 3 (skip if no issues)
    • Review: 4つのレビュースキルを並列実行
      • reviewing-code（sonnet）
      • reviewing-test（sonnet）
      • reviewing-flaky-patterns（sonnet）
      • reviewing-assertion-quality（haiku）
    • Fix: スコア80以上の問題を修正（問題がなければスキップ）
    • 修正後、ExploreエージェントでGATHERED_INFOを再収集して次のイテレーションへ
  10. <TICKET_PATH>/self-refine-report.mdにレポートを書き込み
  11. <TICKET_PATH>/tasks.mdのWorkflowセクションで/self-refineと/tddを完了にマーク
  12. 完了サマリーを日本語で報告

https://github.com/sato-dev1234/claude-code-sample/blob/v1.0/commands/tdd.md#L1-L127

Canon TDD（Red-Green-Refactor）

implementing-tddスキルは、以下のステップでTDDを実行します：

  1. REQUIREMENTS、DESIGN、KNOWLEDGEの解析（resolve_knowledge.pyでナレッジ読み込み）
  2. テストリストの作成（シンプルなものから複雑なものへ順序付け）
  3. 各テストに対してRed-Green-Refactorサイクルを実行
  4. 完了レポートの生成

Red-Green-Refactorサイクル:

  • RED: テストを書いて失敗を確認
  • GREEN: テストが通る最小限の実装
  • REFACTOR: コードを改善し、テストが通ることを確認

実装原則:

  • WHY-firstコメント：理由（ビジネス制約、セキュリティ要件）を書く、HOWは書かない
  • 宣言的コメント：会話調を避け、事実を述べる
  • 入力検証優先：外部入力を受け取る関数は、まず検証を実装

並列実行

テスト数が5個以上の場合、/tddコマンドはテストリストを依存関係に基づいてグループ化し、最大5グループに分割します。各グループは汎用エージェント（general-purpose）で並列実行され、それぞれがimplementing-tddスキルを使用してRed-Green-Refactorサイクルを実行します。

並列実行後、各エージェントの結果（実装ファイル、テスト数）がマージされ、後続の品質改善（self-refine）フェーズに渡されます。

品質改善（self-refine）

TDD実装後、以下の4つのレビュースキルを並列実行してコードとテストの品質を改善します：

  • reviewing-code（sonnet）: プロダクションコードの品質レビュー
  • reviewing-test（sonnet）: テストコードの品質レビュー
  • reviewing-flaky-patterns（sonnet）: フレーキーパターンの検出
  • reviewing-assertion-quality（haiku）: アサーションの品質レビュー

スコア80以上の問題を自動修正し、最大3イテレーションまで実施します。問題が検出されなかった場合は、Fixをスキップして次のイテレーションも実行しません。

成果物

  • 実装ファイル（AC基準を満たすプロダクションコード）
  • テストファイル（テストリストに基づくテストコード）
  • self-refine-report.md（品質改善レポート：コードとテストの統合版）

品質改善サイクル

TDD実装後、自動的にコードとテストの品質改善を実施します。

品質改善は、チェックリスト形式のReview-Fixループで進行します：

- [ ] Review 1
- [ ] Fix 1 (skip if no issues)
- [ ] Review 2 (skip if Fix 1 skipped)
- [ ] Fix 2 (skip if no issues)
- [ ] Review 3 (skip if Fix 2 skipped)
- [ ] Fix 3 (skip if no issues)
  • Review: 4つのレビュースキル（reviewing-code、reviewing-test、reviewing-flaky-patterns、reviewing-assertion-quality）を並列実行し、問題を検出
  • Fix: スコア80以上の問題のみを自動修正

問題が検出されなかった場合、Fixをスキップして次のイテレーションも実行しません。

このサイクルは以下の記事を参考にしています。チェックリストをコマンドに記載しておくと安定してループが行われる印象です。

https://zenn.dev/loglass/articles/c356dbc3062137

並列実行と信頼性スコアの考え方は、Claude Code公式のcode-reviewプラグインを参考にしています。閾値は自由ですが、公式準拠でスコア80以上を修正としています。

https://github.com/anthropics/claude-code/tree/main/plugins/code-review

コメント品質改善: /comment-self-refine

コードのロジックは変更せず、コメントのみを reviewing-comments スキルでレビューし、自動修正します。コメントについては、細かいニュアンスを反映させるのが難解なのと好みもあるため、コマンドを1回まわしたら後は目視でチェックして修正をかけています。

コメントのレビュー・修正をTDDから切り離しているのは、レビューしても残したくないHOWのコメントが残っていたりと精度が安定しない印象があるのと、コメントについてはスコアに関係なく修正してほしいからです。

フロー

  1. 対象チケットの選択（managing-ticketsスキル） → TICKET_PATH
  2. レビュー範囲の選択（AskUserQuestion）
    • uncommitted: git diff HEAD
    • branch: git diff <BASE>...HEAD
  3. Exploreエージェントでdiff + 変更ファイル内容を収集 → GATHERED_INFO（ファイルフィルタリングなし）
  4. Self-Refineループ（チェックリスト形式で実行）：
    - [ ] Review 1
- [ ] Fix 1 (skip if no issues)
- [ ] Review 2 (skip if Fix 1 skipped)
- [ ] Fix 2 (skip if no issues)
- [ ] Review 3 (skip if Fix 2 skipped)
- [ ] Fix 3 (skip if no issues)
    • Review: reviewing-commentsスキルを実行
    • Fix: スコアに関係なくすべてのコメント問題を自動修正（コードロジックは変更しない）
      • /tddのself-refine（スコア80以上のみ修正）とは異なり、全問題を修正
    • 修正後、ExploreエージェントでGATHERED_INFOを再収集して次のイテレーションへ
    • 問題が検出されなかった場合は、Fixをスキップして次のイテレーションも実行しない
  5. <TICKET_PATH>/comment-self-refine-report.mdにレポートを書き込み
    • イテレーション数、修正数
    • イテレーションごとの詳細
    • 残存問題
  6. 完了サマリーを日本語で報告
  7. <TICKET_PATH>/tasks.mdのWorkflowセクションで/comment-self-refineを完了にマーク

成果物

  • comment-self-refine-report.md（コメント品質改善レポート）

Discussion