deep-work

Deep Work

考える工程と入力する工程を分けた構造化ワークフローです。書面の計画がレビューされ、承認されるまで、コードは一切書きません。

ワークフローの概要

Research → Plan → Annotate (repeat 1-6x) → Todo List → Implement → Feedback

すべての成果物はプロジェクトルートではなく、.claude/ 内の Markdown ファイルとして保存されます。

フェーズ 1：調査

他の作業に着手する前に、関連するコードベースを詳細に読み込みます。調査結果を .claude/research.md に記録します。

調査方法：

1. 対象領域のすべてのファイルを読みます。シグネチャだけでなく、実装、エッジケース、エラー処理も確認します
2. データフローを最初から最後までたどります
3. 既存のパターン、規約、ユーティリティ、キャッシュレイヤーを特定します
4. システムの他の部分との統合ポイントを確認します
5. 詳細なレポートを .claude/research.md に記述します

調査の深さの目安： 詳細に読み、複雑な点を理解し、あらゆる内容を確認します。表面的な読み方は認められません。十分に理解できるまで続けてください。

テンプレート： 調査ドキュメントの構成については、references/research-template.md を参照してください。

重要なルール： research.md の作成後は作業を止めます。ユーザーが調査結果を確認し、正確であることを承認するまで、計画に進んではいけません。

フェーズ 2：計画

詳細な実装計画を .claude/plan.md に記述します。変更を提案する前にソースファイルを読み、実際のコードベースに基づいて計画を立てます。

計画に含める内容：

• アプローチとその根拠の説明
• 実際の変更を示すコードスニペット（擬似コードではありません）
• 変更または作成するファイルのパス
• 考慮事項とトレードオフ
• 変更しない項目とその理由

テンプレート： 計画ドキュメントの構成については、references/plan-template.md を参照してください。

参考実装： ユーザーから他のプロジェクトの参考コードが提供された場合は、そのコードを調査し、現在のコードベースのパターンに合うようアプローチを調整します。

重要なルール： 計画の最後に「レビューの準備ができました。.claude/plan.md に直接インラインでメモを追加し、対応が必要になったら知らせてください。」と記載します。実装してはいけません。

フェーズ 3：注釈サイクル

ユーザーが plan.md に直接インラインでメモを追加します。「メモに対応して」などの指示を受けたら、次の手順を実行します。

1. .claude/plan.md を隅々まで読み、ユーザーの注釈をすべて見つけます
2. ユーザーの注釈とは、元の計画に含まれていなかったテキストすべてです。修正、質問、上書き、制約を探します
3. すべての注釈に対応します。セクションを更新し、却下されたアプローチを削除し、ドメイン知識を取り入れます
4. 対応後、注釈のテキスト自体を削除します（計画を整理された状態に保ちます）
5. 最後に「すべてのメモに対応しました。もう一度レビューするか、問題がなければ「タスクリストを追加して」と伝えてください。」と記載します

重要なルール： 実装してはいけません。「まだ実装しないで」という指示は絶対に守る必要があります。ユーザーが明示的に承認するまで、注釈サイクルを繰り返します。

フェーズ 4：タスクリスト

ユーザーが計画を承認したら、詳細なタスクリストを .claude/plan.md に追加します。

## Tasks

### Phase 1: [Phase Name]
- [ ] Task 1 — specific, actionable description
- [ ] Task 2 — specific, actionable description

### Phase 2: [Phase Name]
- [ ] Task 3 — specific, actionable description
- [ ] Task 4 — specific, actionable description

各タスクは、1 回の集中した作業で完了できる程度に小さくします。計画を完全に実装するために必要なすべてのフェーズを含めます。

重要なルール： まだ実装してはいけません。開始する前に、ユーザーの確認を待ちます。

フェーズ 5：実装

ユーザーから「実装して」または「進めて」と指示されたら、次の手順を実行します。

1. 計画内のすべてのタスクを順番に実行します
2. 各タスクの完了後、.claude/plan.md を更新し、- [ ] を - [x] に変更します
3. すべてのタスクが完了するまで止めません
4. 問題を早期に発見するため、各フェーズの後にプロジェクトの型チェッカー／リンターを実行します
5. 不要なコメント、docstring、型の回避策（any、unknown）は追加しません

実装時のコード品質ルール：

• 不要なコメントや jsdoc を追加しない
• any 型や unknown 型を使わない（TypeScript プロジェクト）
• 型チェック／lint を継続的に実行する
• 既存のコードベースのパターンに厳密に従う

フェーズ 6：フィードバック

実装中に、ユーザーから簡潔な修正指示が届くことがあります。計画とセッションに全体のコンテキストがあるため、以下のような指示で十分です。

• 「重複排除関数が抜けています」→ 抜けていたものを実装します
• 「これを管理アプリに移動してください」→ 指示どおりに移動します
• 「もっと広く」／「間隔を2pxに」／「まだ切れています」→ 調整して再確認します
• 「ユーザーテーブルのようにしてください」→ その参考例を確認し、完全に合わせます

元に戻す場合： ユーザーが「すべて元に戻しました」と言った場合は、現在のファイルの状態を再確認し、指定された範囲だけに絞って、改めてきれいに実装します。

プロンプトの参考資料

各フェーズでユーザーがコピーして調整できる、すぐに使えるプロンプトについては、references/prompts.md を参照してください。