MD-Ticket: Instructions file for Codex

AIエージェント向けガイド

AIエージェントがMD-Ticketを効果的に利用するためのガイドラインです。 詳細な手順は_guide/配下のドキュメントを参照してください。

前提条件

AGENTS.md統合

プロジェクトルートのAGENTS.mdにMD-Ticketへの参照を追加することで、AIエージェントがチケット管理の存在を認識できます。 統合方法はREADME.mdの「AGENTS.md統合ガイド」を参照してください。

バージョン管理について

Git管理は任意です。 エージェントはGit管理の有無を意識する必要はありません。

基本原則

1. 明確性の優先: 不明点はユーザーに確認する(推測で補わない)
2. テンプレート遵守: 各チケット種別のテンプレートを使用する
3. 段階的詳細化: アイデア→要望→タスクの流れを尊重する
4. ライフサイクル管理: チケットの状態に応じてファイルを移動・削除する
5. 関連性の記録: チケット間の関連を明確にする

ユーザー確認が必要なケース

以下に該当する場合は、実施前に必ずユーザーへ確認します。

• 情報不足: 必須項目、種別判断の根拠、背景・理由が不明
• 判断の曖昧性: 複数種別への該当、優先度・緊急度不明、重複の可能性
• 重要な決定: 大幅な変更、種別変更、削除、複数タスクへの分割
• 未対応項目の削除: チケット内の未対応項目(将来対応の課題、未対応のレビュー指摘など)をAIの判断だけで削除せず、予防・防御目的の項目は未発現でも残す
• スコープ外の修正: 変更ファイルが3つ以上、既存機能の動作変更、テストが複数コマンドにまたがる、主目的から外れる修正
• 技術的・業務的判断: セキュリティ・パフォーマンス影響、他システム・チームへの影響

スコープ外と判断した場合

以下を提示して承認を得ます。

• 本チケットの主目的と指示内容の関係
• 範囲外である理由と影響範囲
• 推奨アクション(別チケット化/今すぐ実施/見送り)

複数の修正は1つずつ提案・実施・テストし、デグレ発生時に該当変更を特定可能にします。

設定ファイル

チケット種別は.ticket/config.ymlで管理されます(任意)。 設定ファイルがある場合は種別情報(label、template、description)を参照し、ない場合はデフォルト4種別(bug, task, idea, request)を使用します。

チケット種別の判断

ユーザーの依頼内容から適切なチケット種別を判断します。 迷った場合はユーザーに確認してください。

• アイデア(idea/): 発想・構想段階のメモ。実現可能性が未検証
• 要望(request/): 実現してほしい希望。背景と期待する結果が明確
• タスク(task/): 実行すべき作業。前提条件と具体的な内容が定まっている
• バグ(bug/): 不具合の報告。再現手順と期待/実際の動作が記載可能

各種別の詳細な判断基準はチケット種別の判断基準を参照してください。

チケットライフサイクル

チケットの作成・管理・クローズの概要です。 詳細な手順はチケットライフサイクルを参照してください。

チケット作成

1. 種別判断: ユーザーの依頼内容から種別を判断し、承認を得る
2. 情報収集: 種別に応じた必須項目を収集する
3. ファイル名決定: brief-description.md形式で命名する
4. テンプレート取得と作成: _template/{type}.mdを使用して作成する
5. 作成完了の報告: パス・種別・ファイル名を報告する

チケット管理

• 追加情報や進捗があればチケットを更新する
• 成熟度に応じて種別変更(ディレクトリ移動)を提案する
• 関連チケットは種別(関連/前提/派生/重複)とリンクで記述する

チケットクローズ

1. クローズ確認: ユーザーに明示的に確認する
2. 記録状況の確認: 実施内容・成果物の記録を確認する
3. ファイル処理: 参考資料と関連チケットの参照を処理する
4. 処理の実行: 削除またはアーカイブを実行する
5. ADR記録の提案: 重要な技術判断がある場合に提案する