code-assist

コードアシスト

概要

探索、計画、実装、コミットのワークフローで、テスト駆動開発を用いたコードタスクの実装をガイドします。既存のパッケージパターンに従い、可読性と拡張性を優先しながら、自動化とユーザーとの協働のバランスを取ります。

パラメーター

• task_description（必須）：タスクの仕様、概要、.code-task.md のファイルパス、または URL
• additional_context（任意）：実装コンテキストを補足する情報
• documentation_dir（任意、デフォルト：「.sop/planning」）：計画ドキュメントのディレクトリ
• repo_root（任意、デフォルト：現在の作業ディレクトリ）：コード実装のリポジトリルート
• task_name（任意）：短く内容を表す名前（指定されない場合は自動生成）
• mode（任意、デフォルト：「auto」）：「interactive」（各ステップで確認）または「auto」（自律実行）

制約：

• 繰り返し中断しないよう、すべてのパラメーターを最初に一度のプロンプトで尋ねる必要があります
• 入力を検証する必要があります。mode を「interactive」または「auto」に正規化し、パスを検証し、必要に応じて task_name を生成してください

モードの動作

すべてのステップで、次のパターンを適用してください。

インタラクティブモード： 実行する操作を提示して確認を求めます。複数の方法がある場合は、長所と短所を説明します。明確化のための質問をします。重要な判断ポイントでは一時停止します。学習に役立つ背景情報を提供します。

自動モード： 自律的に実行します。進捗を記録する progress.md に、すべての判断と理由を記載します。最適な方法を選び、その理由を記録します。完了時に包括的な概要を提示します。

重要な注意事項

関心事の分離： ドキュメントは {documentation_dir} に保存します。コード（テストと実装）は repo_root に保存します。両者を混在させないでください。ドキュメントでは、実装そのものではなく、実装の指針となる高レベルの概念を説明します。ドキュメントにコードスニペットを含める場合は、短くまとめ、例または参考資料であることを明記します。

CODEASSIST.md との連携： repo_root に CODEASSIST.md が存在する場合は読み込み、その制約を全体を通して適用します。

手順

1. セットアップ

プロジェクト環境を初期化し、必要なディレクトリ構成を作成します。

制約：

• 次に進む前に、{documentation_dir}/implementation/{task_name}/（logs サブディレクトリを含む）を作成し、存在することを確認する必要があります
• 指示ファイル（CODEASSIST.md、README.md、CONTRIBUTING.md、ARCHITECTURE.md など）を必ず見つけ、関連情報を context.md にまとめる必要があります
• context.md（プロジェクト構造、要件、パターン、依存関係）と progress.md（Markdown のチェックリストによる実行状況の記録）を必ず作成する必要があります
• task_description が YAML フロントマター付きの .code-task.md を指している場合、status: in_progress と started: <date> がまだ設定されていなければ更新します

💬 モードごとの操作方法については、モードの動作を参照してください

2. 探索フェーズ

2.1 要件とコンテキストの分析

タスクの説明と既存のドキュメントを分析し、主要な機能、エッジケース、制約を特定します。

制約：

• 概要レベルの説明からでも、機能要件と受け入れ基準を明確に列挙する必要があります
• 適切なファイルパス、言語、既存のプロジェクト構造との整合性を判断する必要があります
• インタラクティブモードでは、ユーザーと要件について話し合い、不明点を明確にし、理解が正しいか確認します

💬 モードごとの操作方法については、モードの動作を参照してください

2.2 既存パターンの調査

類似の実装を検索し、実装が連携するインターフェース、ライブラリ、コンポーネントを特定します。

制約：

• 関連するコード、パターン、規約をリポジトリ内で必ず検索する必要があります
• 依存関係マップを作成し、実装パスを context.md に反映する必要があります

💬 モードごとの操作方法については、モードの動作を参照してください

3. 計画フェーズ

3.1 テスト戦略の設計

通常の動作、エッジケース、エラー条件を網羅するテストシナリオを作成します。

制約：

• すべての受け入れ基準を、少なくとも1つのテストシナリオで必ず網羅してください
• 明示的な入力／出力のペアを定義し、シナリオを plan.md に必ず保存してください
• 初期状態で失敗するテストを必ず設計してください（設計中にモック実装を使用しないでください）

💬 モード固有の操作ガイダンスについては、モードの動作を参照してください

3.2 実装計画と進捗管理

大まかな構成をまとめ、実装計画を作成します。

制約：

• 主要な実装タスクを含む計画を plan.md に必ず保存してください
• Markdown のチェックボックス形式を使用して、progress.md に実装チェックリストを必ず維持してください
• 対話モードでは、複数のアプローチをメリット／デメリットとともに提示し、トレードオフについて話し合ってください

💬 モード固有の操作ガイダンスについては、モードの動作を参照してください

4. コードフェーズ

フェーズ全体の制約：

• すべてのコード（テストと実装）は必ず repo_root に配置してください。documentation_dir には配置しないでください
• 次のサブステップに進む前に、テスト／ビルドが通ることを必ず確認してください
• 既存のコードベースの規約（命名、パターン、エラー処理、テストのスタイル）に必ず従ってください
• ビルド出力を {documentation_dir}/implementation/{task_name}/logs/ にパイプし、成功／失敗を示す文字列を検索してください

4.1 テストケースの実装

厳格な TDD の原則に従ってテストケースを記述します。

制約：

• 実装コードを書く前に、すべての要件に対するテストを必ず実装してください
• 想定どおりに失敗することを確認するため、テストを必ず実行し、失敗理由を記録してください
• 既存のコードベースで使用されているテストフレームワークの規約に必ず従ってください

💬 モード固有の操作ガイダンスについては、モードの動作を参照してください

4.2 実装コードの開発

まずはシンプルさと正確さを重視して、テストに合格する実装コードを記述します。

制約：

• TDD サイクル（RED → GREEN → REFACTOR）に必ず従ってください
• 現在のテストに合格するために必要なものだけを必ず実装してください（YAGNI、KISS、SOLID）
• 実装の各ステップの後にテストを必ず実行し、合格することを確認してください

💬 モード固有の操作ガイダンスについては、モードの動作を参照してください

4.3 リファクタリングと最適化

実装を見直し、簡素化、改善、規約への準拠を図ります。

制約：

• 開始前にすべてのテストとビルドが通ることを必ず確認してください。失敗があれば、まず修正してください
• 実装を周囲のコードベースの規約（命名、構成、エラー処理、インポート、ログ出力）に必ず合わせてください
• リファクタリング中もテストが合格する状態を必ず維持してください

💬 モード固有の操作ガイダンスについては、モードの動作を参照してください

4.4 実装の検証

実装が完全で正しいことを検証します。

制約：

• テストスイート全体とビルドを必ず実行し、すべて合格することを確認してください
• 実装計画のすべての項目が完了していることを必ず確認してください
• テストが失敗している間は、完了したと主張してはいけません

💬 モード固有の操作ガイダンスについては、モードの動作を参照してください

5. コミットフェーズ

Conventional Commits に準拠したコミットメッセージを作成し、git commit を実行します。

制約：

• ビルドとテストの合格を確認するまでは、コミットしてはいけません
• Conventional Commits の仕様に必ず従ってください
• リモートリポジトリに push してはいけません
• task_description が .code-task.md だった場合、コミット前に frontmatter を status: completed および completed: <date> に更新してください
• コミットハッシュを progress.md に記録してください

💬 モード固有の操作ガイダンスについては、モードの動作を参照してください

期待される成果

• すべての要件を満たし、十分にテストされた実装
• 実装を検証する包括的なテストスイート
• 既存のパターンに従い、読みやすさを優先して過剰な設計を避けた、クリーンなコード
• {documentation_dir}/implementation/{task_name}/ 内の実装成果物（context.md、plan.md、progress.md、logs/）
• 適切なコミットメッセージによる変更のコミット

例

機能の実装

入力：

task_description: "Create a utility function that validates email addresses"
mode: "interactive"

想定されるプロセス：

1. CODEASSIST.md を確認し、指示ファイルを探します
2. 既存ファイル（pom.xml、package.json など）からプロジェクトの種類を判定します
3. .sop/planning/implementation/email-validator/ にディレクトリ構造を作成します
4. 要件を調査し、コンテキストのドキュメントを作成します
5. 有効／無効なメール形式のテストシナリオを計画します
6. 先にテストを実装します（TDD アプローチ）
7. 検証関数を実装します
8. 適切なコミットメッセージでコミットします

トラブルシューティング

ディレクトリ／権限の問題： 可能であればディレクトリを作成し、権限の問題があればユーザーに伝えて、代替案を提案します。

ビルドの失敗： CODEASSIST.md のガイダンスを確認し、正しいディレクトリにいることを確かめて、クリーンビルドを試し、依存関係を確認します。

複数パッケージの調整： 依存関係の順序を確認し、順番にビルドして、パッケージごとに個別のコミットを作成します。

タスクファイルのフロントマターの問題： フロントマターが存在しないか不正な形式の場合、更新をスキップします。フロントマターの問題を理由にタスクを失敗させないでください。

実装上の課題： progress.md に記録し、代替案を提案します。対話モードでは指示を求め、自動モードでは最も有望な方法を選び、その判断を記録します。

成果物

• {documentation_dir}/implementation/{task_name}/context.md — ワークスペースの構成、要件、パターン、依存関係、実装パス • {documentation_dir}/implementation/{task_name}/plan.md — テストシナリオ、実装方針 • {documentation_dir}/implementation/{task_name}/progress.md — 実行状況、TDD サイクル、コミット状況、課題 • {documentation_dir}/implementation/{task_name}/logs/ — ビルド出力