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
│   ├── steering-workflow.md
│   └── documentation.md
├── skills/               # Slash-command workflows
│   ├── steering/         # /steering — plan/implement/review cycle
│   ├── 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
│   ├── check-tasklist.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	絵文字コミットプレフィックス、機能単位のコミット粒度、ブランチ命名規則
steering-workflow.md	コードを書く前に .steering/ ドキュメントを作成する。隔離のために worktree を使用する
documentation.md	永続的ドキュメント（docs/）と作業単位ドキュメント（.steering/）を分離する

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

Skills

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

コアワークフロー Skills

スキル	コマンド	説明
Steering	/steering plan <feature>	要件定義書、設計書、タスクリストを作成する
	/steering implement <path>	進捗を追跡しながらタスクリストを実行する
	/steering review <path>	実装後の振り返り
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/ に新しいルールファイルを追加する

例：Steering スキルの使用

# 1. Plan a feature
> /steering plan jsx-highlighting

# Claude creates .steering/20260222-001-jsx-highlighting/ with:
#   requirements.md, design.md, tasklist.md

# 2. Review and approve the documents, then implement
> /steering implement .steering/20260222-001-jsx-highlighting

# 3. After implementation, review
> /steering review .steering/20260222-001-jsx-highlighting

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)	ルールファイル内の否定的な表現をブロックする
check-tasklist.sh	Stop	タスクリストに未完了のタスクがある場合に警告する
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" }] }
    ],
    "Stop": [
      { "hooks": [{ "command": ".claude/hooks/check-tasklist.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 セッションでコンテキストとして利用可能になります。

ステアリングワークフロー

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

1. Plan

3つのドキュメントを含む .steering/ ディレクトリを作成します：

.steering/20260222-001-jsx-highlighting/
├── requirements.md   # What to build (user-approved)
├── design.md         # How to build it (user-approved)
└── tasklist.md       # Step-by-step tasks (user-approved)

ディレクトリ名の形式は [YYYYMMDD]-[NNN]-[title] で、NNN は連番です。

2. Implement

tasklist.md のタスクを1つずつ進めます：

• 各タスクの開始時（完了時ではなく）に [ ] → [x] に更新する

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

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

3. Review

実装後：

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

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

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

• マージタスクを含むすべてのタスクリスト項目を [x] にする

• ユーザーの承認を得て main にマージする

セッションの復元

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

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

2. 最新の .steering/*/tasklist.md を検索する

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. スキルまたは手動での呼び出しから参照する