Claude Code 開発ワークフロー

このガイドでは、claude-project-template から構築されたプロジェクトで Claude Code を使用する方法を説明します。テンプレートは、規約を強制し定型作業を自動化する Rules、Skills、Hooks、Agents による構造化された開発ワークフローを提供します。

概要

Claude Code は Anthropic の AI 支援ソフトウェア開発用 CLI ツールです。テンプレートは以下の要素で構成されています：

• Rules — コーディング規約の強制（テスト、コメント、Git 規約）

• Skills — ワークフローの自動化（レビュー、コミット、セッション復元）

• Hooks — ミスの防止（force-push のブロック、編集の検証）

• Agents — 専門タスクの委譲（コードレビュー、ビルドエラー解決）

• Commands — 複数ステップのプロジェクトセットアップワークフロー

すべての設定はプロジェクトルートの .claude/ ディレクトリに格納されています。

ディレクトリ構成

.claude/
├── rules/                # Behavioral rules Claude Code follows
│   ├── testing.md
│   ├── code-comments.md
│   ├── git-conventions.md
│   ├── issue-workflow.md
│   └── documentation.md
├── skills/               # Slash-command workflows
│   ├── catchup/          # /catchup — restore session state
│   ├── review/           # /review — code review
│   ├── review-docs/      # /review-docs — document quality review
│   ├── git-workflow/     # /git-workflow — branch/commit/PR automation
│   ├── add-feature/      # /add-feature — full feature implementation
│   ├── add-rule/         # /add-rule — add new rules
│   ├── development-guidelines/  # /development-guidelines
│   ├── implementation-validator/  # /implementation-validator
│   └── prd-writing/      # /prd-writing — PRD creation
├── commands/             # Multi-step command workflows
│   └── setup-project.md  # Initial project setup
├── agents/               # Subagent definitions
│   ├── code-reviewer.md  # Automated code review checklist
│   └── build-resolver.md # Build error diagnosis
├── hooks/                # Shell scripts triggered by events
│   ├── validate-bash.sh
│   ├── validate-file-edit.sh
│   ├── pre-compact-save.sh
│   ├── session-info.sh
│   └── check-prohibition-language.sh
├── settings.json         # Shared permissions and hook config
└── settings.local.json   # Local-only permissions (not committed)

Rules

Rules は .claude/rules/ 内の Markdown ファイルで、必須の動作制約を定義します。Claude Code はすべてのやり取りでこれらを読み込みます。

ルールファイル	目的
testing.md	すべてのコード変更にテストを要求する。テストは src/test/ にソース構造を反映して配置
code-comments.md	クラスおよび非自明なメソッドに英語の KDoc コメントを要求する
git-conventions.md	絵文字コミットプレフィックス、機能単位のコミット粒度、ブランチ命名規則
issue-workflow.md	コードを書く前に GitHub Issue を起票（または既存 Issue を利用）し、Definition of Done チェックリストを記載する。隔離のために worktree を使用する
documentation.md	永続的ドキュメント（docs/）と作業単位の記録（GitHub Issue）を分離する

Rules は命令形で記述され、交渉の余地のない制約として扱われます。新しいルールを追加するには、.claude/rules/ に .md ファイルを作成し、CLAUDE.md から参照してください。

Skills

Skills は /<skill-name> で呼び出すスラッシュコマンドワークフローです。各スキルには動作を定義する SKILL.md ファイルがあります。

コアワークフロー Skills

スキル	コマンド	説明
Catchup	/catchup	/clear またはコンテキスト圧縮後にセッション状態を復元する
Review	/review	未コミットの変更に対してコードレビューを実行する
Git Workflow	/git-workflow branch	命名規則に従ってブランチを作成する
	/git-workflow commit	絵文字プレフィックスを自動検出しコミットメッセージを生成する
	/git-workflow pr	タイトル、概要、テスト計画付きの PR を作成する
	/git-workflow status	ブランチの状態と規約のリマインダーを表示する

コード品質 Skills

スキル	コマンド	説明
Review Docs	/review-docs	5つの基準（完全性、明確性、一貫性、実装可能性、測定可能性）でドキュメントを評価する
Implementation Validator	/implementation-validator	5つの基準（仕様準拠、コード品質、テストカバレッジ、セキュリティ、パフォーマンス）でコードを検証する
Development Guidelines	/development-guidelines	コーディングガイドラインの確認または作成

プロジェクトセットアップ Skills

スキル	コマンド	説明
PRD Writing	/prd-writing	テンプレートからプロダクト要求定義書を作成する
Add Feature	/add-feature	機能実装の完全なワークフロー（コード + テスト + コミット）
Add Rule	/add-rule	.claude/rules/ に新しいルールファイルを追加する

Commands

.claude/commands/ 内の Commands は、複数のスキルを組み合わせたマルチステップワークフローを定義します。

コマンド	ファイル	ステップ
setup-project	commands/setup-project.md	アイデアを読む → PRD を作成 → 機能設計書を作成

Commands はスキルと同じ方法で呼び出します：/setup-project。機能追加は add-feature スキル（skills/add-feature/）で駆動します。

Agents

Agents は Claude Code が専門ワーカーとして起動するサブエージェント定義です。隔離されたコンテキストで実行され、構造化されたレポートを返します。

code-reviewer

8項目の自動コードレビューを実行します：

1. ドキュメントコメントの有無

2. 変更に対するテストファイルの存在

3. 自動生成ファイルが手動編集されていないこと

4. パッケージ/モジュール構造が規約に準拠していること

5. コードスタイルの準拠

6. テスト品質（意味のあるアサーション、デッドコードなし）

7. デッドコード検出（未使用インポート、コメントアウトされたブロック）

8. エッジケースのカバレッジ（null/空値、境界値、エラー処理）

出力：各項目に PASS/WARN/FAIL が付いた Markdown チェックリスト。

build-resolver

4つのステップでビルドエラーを診断します：

1. CLAUDE.md のビルドコマンドを使用してエラーを再現する

2. 分類：コンパイル / ビルド設定 / 依存関係 / フレームワーク API / コード生成

3. 根本原因の特定（ファイル、行、コンテキスト）

4. 具体的なコード変更として修正案を提示する

Hooks

Hooks は Claude Code のイベントに応じて自動実行されるシェルスクリプトです。.claude/settings.json で設定します。

フックスクリプト	トリガー	動作
validate-bash.sh	PreToolUse (Bash)	git add .、git push --force、rm -rf をブロックする
validate-file-edit.sh	PreToolUse (Edit/Write)	自動生成ファイルへの編集をブロックする（カスタマイズ可能）
check-prohibition-language.sh	PostToolUse (Edit/Write)	ルールファイル内の否定的な表現をブロックする
pre-compact-save.sh	PreCompact	セッション状態を .claude/session-state.md に保存する
session-info.sh	SessionStart	開発環境の情報を表示する（ブランチ、ツールバージョン）

フックの終了コード

コード	意味
0	許可（メッセージなし）
0 + stdout	情報メッセージ付きで許可
2	stderr のエラーメッセージと共にアクションをブロック

例：validate-bash.sh

#!/bin/bash
# Reads tool input from stdin as JSON
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.command // empty')

if echo "$COMMAND" | grep -qE 'git\s+push\s+.*--force'; then
  echo "BLOCKED: Force push is not allowed." >&2
  exit 2
fi
exit 0

設定

settings.json（共有）

共有設定ファイルは、すべての開発者に対する権限とフックを設定します：

{
  "permissions": {
    "allow": [
      "Bash(git status)", "Bash(git diff *)", "Bash(git log *)",
      "Bash(git branch *)", "Bash(git checkout *)"
    ],
    "deny": [
      "Bash(cat .env*)", "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "command": ".claude/hooks/validate-bash.sh" }] },
      { "matcher": "Edit|Write", "hooks": [{ "command": ".claude/hooks/validate-file-edit.sh" }] }
    ]
  }
}

settings.local.json（ローカル専用）

ローカル設定は開発者固有の権限設定用です。このファイルはバージョン管理にコミットしません：

{
  "permissions": {
    "allow": [
      "Bash(git commit *)"
    ]
  }
}

永続的ドキュメント

docs/ ディレクトリには、プロジェクトと共に発展する永続的なプロジェクトドキュメントが格納されています：

ファイル	目的
product-requirements.md	プロダクトビジョン、ユーザーストーリー、機能ロードマップ
functional-design.md	コンポーネント設計、Extension Point マッピング
architecture.md	技術スタック、制約条件、パフォーマンス要件
development-guidelines.md	コーディング規約、テスト規約
repository-structure.md	ソースコードのレイアウト、ファイル配置ルール
glossary.md	ドメイン用語の定義

これらのドキュメントは CLAUDE.md から @docs/filename.md 構文で参照され、すべての Claude Code セッションでコンテキストとして利用可能になります。

Issue ワークフロー

Issue ワークフローはコア開発プロセスです。軽微でないすべてのコード変更は、このサイクルに従います：

1. Plan

既存の GitHub Issue を利用するか新規に起票し、そこに Definition of Done チェックリストを記載します：

• 自分で起票した Issue：Issue 本文に ## Definition of Done セクションを追加する

• 他者が起票した Issue：元の報告本文は編集せず、チェックリストをコメントとして投稿する

チェックリストには受け入れ条件と、マージ可能な単位（実装 + テスト + ドキュメント）ごとのセクションを記載します。チェックリストを記載したらすぐに実装を開始し、レビューはプルリクエストとマージ確認の際に行います。

2. Implement

Definition of Done の項目を1つずつ進めます：

• 各項目が完了したら、Issue 上のチェックリストをその場で編集して [ ] → [x] に更新する

• 実装は git worktree 内で行う（main から隔離）

• 機能単位の粒度でコミットする（実装 + テスト + 設定 = 1コミット）

3. Review

実装後：

• /review で自動コードレビューを実行する

• ビルドの成功を確認する：./gradlew buildPlugin

• テストの成功を確認する：./gradlew test

• Definition of Done のすべての項目が [x] であることを確認する

• ユーザーの承認を得て、Issue を参照（Closes #<番号>）しつつ main にマージする

セッションの復元

コンテキストが圧縮またはクリアされた場合、/catchup で復元します：

1. .claude/session-state.md から保存された状態を読み込む

2. 対応中の Issue を特定し、その Definition of Done を読み込む

3. 現在のブランチ、変更ファイル、次の未完了項目を報告する

カスタマイズ

新しいルールの追加

1. 明確で命令形の制約を記述した .claude/rules/<rule-name>.md を作成する

2. CLAUDE.md のルールセクションに @.claude/rules/<rule-name>.md を追加する

3. 強制ルールには必須の前文を使用する：

   以下は強制的な行動指示であり、例外なく従うこと。

新しいスキルの追加

1. .claude/skills/<skill-name>/SKILL.md を作成する

2. スキルのトリガー、入力、ステップ、出力形式を定義する

3. スキルは /<skill-name> として利用可能になる

新しいフックの追加

1. .claude/hooks/<hook-name>.sh を作成する（実行権限を付与すること）

2. .claude/settings.json の適切なトリガーに登録する

3. 終了コード 0 で許可、2 でブロックする

新しいエージェントの追加

1. .claude/agents/<agent-name>.md を作成する

2. エージェントのチェックリスト、分析ステップ、出力形式を定義する

3. スキルまたは手動での呼び出しから参照する