株式会社ジェイテックジャパン CTOの高丘 @tomohisaです。最近、Claude CodeやCursor IDEなどのAIエージェントを活用した開発が増えてきており、並列で複数のプロジェクトを動かしたいシーンが多くなってきました。
Claude Codeにおける長時間タスクのコンテキスト管理の課題
Claude Codeによる開発効率の改善は、長時間のタスクを実行できるという点で大きなメリットがあります。しかし、コンテキストの制約により、長い作業を正確に処理するためにはタスクの分割が重要になります。
Claude Codeがタスクを実行する際、以下のような特徴があります：
- AIエージェント機能: Claudeが自律的にコーディング作業を実行
- マルチタスク処理: 複数のプロセスを並列実行
- カスタムスラッシュコマンド: プロジェクト固有のワークフローを定義可能
しかし、長時間のタスクにおいては、親プロセスから子プロセスへどの程度の情報が引き継がれるかは不明確です。特に近年のAIシステムではテキストのコンパクション（圧縮）が行われることがあり、この処理により全体のコンテキストから「重要」と判断された部分のみが残され、その他の情報は省略されてしまいます。この結果、省略された重要な詳細が無視され、開発者の意図とは異なる予期しない結果や行動を引き起こすことが頻繁に発生します。
そこで個人的にはコンテキストが共有されなくても良い仕組みを構築することが重要だと考えています。
そのために有効なのが、マークダウンファイルによる情報継承の仕組みです。
ファイルベースワークフロー設計
基本的な考え方
各サブタスクが前のコンテキストに依存せず、ファイルシステムを通じて必要な情報を取得できるように設計します。
具体的なファイル構成
tasks/
└── 233/ # GitHub Issue番号
├── issue.md # 要件定義（GitHubから取得）
├── progress.md # 進捗管理
└── design.md # 設計書
情報継承のフロー
-
要件取得フェーズ:
issue.mdを作成 -
進捗管理フェーズ:
progress.mdで現在の状況を管理 -
設計フェーズ:
issue.mdとprogress.mdを参照してdesign.mdを作成 -
実装フェーズ:
design.mdを参照してコードを実装
このアプローチにより、各フェーズが独立して実行でき、プロセス間でのコンテキスト共有が不要になります。
カスタムスラッシュコマンドとは
カスタムスラッシュコマンドは、Claude Codeで利用できる強力な機能の一つです。これにより、プロジェクト固有のワークフローを定義し、繰り返し作業を自動化できます。
基本的な使い方
-
定義場所:
.claude/commands/ディレクトリ内のマークダウンファイル -
呼び出し方法: コマンド入力画面で
/を入力後、カスタムメニューから選択 - 引数の渡し方: コマンド名の後にスペース区切りで引数を指定
実際の使用例
/project:myproj:startdevelop 233
このようなコマンドを引数付きで呼び出すことにより、引数によってタスクの作業フォルダを指定することができます。上記の例では、GitHubのIssue番号233を渡すことで、作業フォルダtasks/233が自動的に設定されます。
ファイル構造
.claude/
└── commands/
├── project-startdevelop.md # メインワークフロー
├── makeissuefilefromnumber.md # Issue取得コマンド
├── gitsync.md # Git同期コマンド
└── sub/
├── dev-domain-progress.md # 進捗管理
├── dev-domain-planning.md # 設計作業
├── dev-domain-coding.md # 実装作業
└── dev-domain-coding-check.md # テスト実行
サブコマンド呼び出しの課題と解決策
当初の課題
最初は、メインコマンドからサブコマンドを呼び出すことが安定せず、以下の問題がありました：
- 日本語指示の不安定性: 日本語でも半分程度の確率でしか実行されず、英語での指示はさらに成功率が低い傾向がありました
- コマンド名の誤解: CLIコマンドと勘違いしてシェルファイルを探そうとする
- 実行の不確実性: 想定した通りに動作しないケースが多発
解決策: マークダウンファイル実行という指示方法への転換
Claude Code自身との相談を重ね、従来の「カスタムスラッシュコマンドを呼び出す」という指示ではなく、「マークダウンファイルを読んで実行する」という指示方法に変更することで、安定して実行できるようになりました。この方法では、スラッシュコマンドという概念を前面に出さず、あくまで「特定のマークダウンファイルの内容を実行する」という自然な指示を行います。
効果的な（サブ）カスタムスラッシュコマンドを呼び出す記述方法
成功例: メインワークフローの記述方法
以下は、安定して動作するカスタムスラッシュコマンドの実装例です：
# Start Domain Development from Issue
<!-- /project:dev-domain-from-issue $ARGUMENTS -->
## Purpose
**Start development work from GitHub Website Issue #$ARGUMENTS.**
## Input Validation
**🚨 IMPORTANT: First check if Issue number is provided as argument 🚨**
If `$ARGUMENTS` is empty, undefined, or not a valid positive integer:
- Display error: `● エラー: Issue番号が必要です。引数を指定してください。 😅`
- Display usage example: `例: /dev-domain-from-issue 200`
- **STOP execution immediately - do not proceed with any subsequent steps**
Only proceed with the following steps if a valid Issue number is provided.
## Execution Steps
Execute the following steps **in sequential order**. Each step is a custom slash command that should be executed as a separate task.
**🔴 IMPORTANT: Each numbered item below is a complete task that you must execute independently. Read the command file from `.claude/commands/` and execute its contents. Do NOT just display the command name. 🔴**
### Step-by-Step Execution Instructions:
1. **Initialize Progress Tracking**
- Read and execute: `.claude/commands/sub/dev-domain-progress.md`
- Pass argument: `$ARGUMENTS`
- Purpose: Create file and initialize TODO management
2. **Create Issue File**
- Read and execute: `.claude/commands/makeissuefilefromnumber.md`
- Pass argument: `$ARGUMENTS`
- Purpose: Create file for Issue #$ARGUMENTS
3. **Git Sync - Start**
- Read and execute: `.claude/commands/gitsync.md`
- Pass argument: `"Domain Coding Start working on Issue #$ARGUMENTS"`
- Purpose: Git sync before starting work
4. **Domain Planning**
- Read and execute: `.claude/commands/sub/dev-domain-planning.md`
- Pass argument: `$ARGUMENTS`
- Purpose: Execute Issue design and analysis
5. **Git Sync - Planning Complete**
- Read and execute: `.claude/commands/gitsync.md`
- Pass argument: `"Domain Coding Finished on Issue #$ARGUMENTS"`
- Purpose: Git sync when coding is completed
6. **Domain Coding**
- Read and execute: `.claude/commands/sub/dev-domain-coding.md`
- Pass argument: `$ARGUMENTS`
- Purpose: Execute Issue implementation and coding
7. **Git Sync - Coding Complete**
- Read and execute: `.claude/commands/gitsync.md`
- Pass argument: `"Domain Coding Finished on Issue #$ARGUMENTS"`
- Purpose: Git sync when coding is completed
8. **Domain Coding Check**
- Read and execute: `.claude/commands/sub/dev-domain-coding-check.md`
- Pass no arguments
- Purpose: Execute Issue implementation and coding check
実際には上記の英語のワークフローを使用していますが、日本語に訳すと以下のような内容になります：
# Issueからドメイン開発を開始
<!-- /project:dev-domain-from-issue $ARGUMENTS -->
## 目的
**GitHub WebサイトのIssue #$ARGUMENTSから開発作業を開始する。**
## 入力検証
**🚨 重要: まず引数としてIssue番号が提供されているかを確認する 🚨**
`$ARGUMENTS`が空、未定義、または有効な正の整数でない場合：
- エラー表示: `● エラー: Issue番号が必要です。引数を指定してください。 😅`
- 使用例表示: `例: /dev-domain-from-issue 200`
- **即座に実行を停止 - 以降の手順は実行しない**
有効なIssue番号が提供されている場合のみ、以下の手順を続行する。
## 実行手順
以下の手順を**順次実行**する。各手順は個別に実行すべき完全なタスクです。
**🔴 重要: 以下の各番号付き項目は独立して実行すべき完全なタスクです。`.claude/commands/`からコマンドファイルを読み込んで内容を実行してください。コマンド名を表示するだけではダメです。🔴**
### 段階的実行指示:
1. **進捗追跡の初期化**
- 読み込んで実行: `.claude/commands/sub/dev-domain-progress.md`
- 引数を渡す: `$ARGUMENTS`
- 目的: ファイル作成とTODO管理の初期化
2. **Issueファイルの作成**
- 読み込んで実行: `.claude/commands/makeissuefilefromnumber.md`
- 引数を渡す: `$ARGUMENTS`
- 目的: Issue #$ARGUMENTS用のファイルを作成
3. **Git同期 - 開始**
- 読み込んで実行: `.claude/commands/gitsync.md`
- 引数を渡す: `"Issue #$ARGUMENTSでドメインコーディング開始"`
- 目的: 作業開始前のGit同期
4. **ドメイン設計**
- 読み込んで実行: `.claude/commands/sub/dev-domain-planning.md`
- 引数を渡す: `$ARGUMENTS`
- 目的: Issue設計と分析の実行
5. **Git同期 - 設計完了**
- 読み込んで実行: `.claude/commands/gitsync.md`
- 引数を渡す: `"Issue #$ARGUMENTSでドメイン設計完了"`
- 目的: 設計完了時のGit同期
6. **ドメインコーディング**
- 読み込んで実行: `.claude/commands/sub/dev-domain-coding.md`
- 引数を渡す: `$ARGUMENTS`
- 目的: Issue実装とコーディングの実行
7. **Git同期 - コーディング完了**
- 読み込んで実行: `.claude/commands/gitsync.md`
- 引数を渡す: `"Issue #$ARGUMENTSでドメインコーディング完了"`
- 目的: コーディング完了時のGit同期
8. **ドメインコーディングチェック**
- 読み込んで実行: `.claude/commands/sub/dev-domain-coding-check.md`
- 引数なし
- 目的: Issue実装とコーディングのチェック実行
記述方法のポイント
この記述方法には以下の重要な特徴があります：
- マークダウンファイルとして実行: スラッシュコマンドとは明記せず、「マークダウンを読んで実行する」と記述
-
引数の明確な指定:
$ARGUMENTSを使用して引数の受け渡しを明確化 - 実行手順の詳細化: 各ステップでやるべきことを具体的に記述
- エラーハンドリング: 引数の検証やエラー時の処理を明記
なぜこの方法が効果的なのか
従来は「スラッシュコマンドを呼び出す」という指示をしていましたが、実際にはマークダウンファイルを読み込んで実行させる方が確実でした。これにより：
- 誤解の防止: CLIコマンドとの混同を避けられる
-
引数の確実な受け渡し:
$ARGUMENTSによる明確な引数指定 - 実行の安定性: 今のところ100%の確率で想定通りに動作
ワークフロー実装の実際の効果
このワークフローアプローチを導入することで、比較的長い処理を段階的かつ確実に実行できるようになりました。具体的には：
- 設計の徹底: 要件から設計書を確実に作成
- 実装の精度向上: 設計書に基づいた実装
- 品質保証: ビルドチェックとテストの自動実行
実装における課題と改善点
完璧ではありませんが、以下のような改善が見られました：
改善された点
- 各段階での成果物が確実に作成される
- プロセスの追跡が容易になった
- 再現性のあるワークフローの確立
まだ残る課題
- 途中で処理が停止することがある
- ビルドエラーが残ったまま次の工程に進むことがある
- 100%の精度は実現していない
継続的な改善アプローチ
これらの課題に対して、ワークフローとサブワークフローの内容を継続的に調整することで精度向上を図っています。
実際の適用事例：Sekibanフレームワークを使ったイベントソーシングバックエンド開発
私たちが開発しているSekiban（イベントソーシング・CQRSフレームワーク）を使用して、C#でイベントソーシングバックエンドを構築する際に、このワークフローを活用してドメインモデルの実装を行っています。
適用のポイント
Sekibanフレームワークを使ったイベントソーシングバックエンドの開発において、このワークフローの効果を最大化するために重要なのは、設計時や実装時に渡すコンテキストの精度を高めることです。具体的には、過去の成功事例をテンプレート化して蓄積し、Claude Codeが新しい実装を一から生成するのではなく、既存のパターンを参考にして実装を行うアプローチを採用しています。これにより、一貫性のある高品質なコードが安定して生成されるようになりました。
チーム文化としてのAI開発環境構築
このワークフローの構築は、単なる技術的な実装以上に、チームの文化を作るような感覚があります。
標準化されたプロセスにより誰でも同じ品質で作業できるようになり、成功パターンをライブラリ化することで組織的な知識の蓄積が進みます。また、失敗から学びプロセスを継続的に改善する文化が根付き、すべての作業過程がファイルとして残ることで透明性の高い開発環境が実現されます。
今後の展望
このワークフローアプローチをさらに発展させ、異なるプログラミング言語への適用や業界標準のワークフローテンプレート作成を検討しています。また、各工程の成功率や所要時間を測定するメトリクス収集システムの構築や、より効果的なプロンプトエンジニアリングによるAI学習の最適化にも取り組んでいく予定です。
まとめ
Claude Codeのカスタムスラッシュコマンドを活用することで、プロセス間でファイルベースの情報共有を行うコンテキスト非依存の設計、標準化されたプロセスによる再現性のあるワークフロー、継続的な改善による段階的な品質向上、そしてチーム全体での知識共有と標準化による開発文化の構築が実現できました。
特に重要なのは、マークダウンファイルとして実行する記述方法の確実性、$ARGUMENTSを活用した引数の明確な指定、ファイルベースの情報継承によるコンテキスト問題の解決、そして継続的な改善によるワークフローの精度向上です。
Claude Codeは単なるAIツールではなく、開発チームの文化を形成する重要なパートナーとなり得ます。このようなワークフローの標準化により、AI駆動開発の新しい可能性が開かれることを期待しています。
今後も実践を通じて得られた知見を共有していきますので、よろしければ参考にしてください。
Discussion