manifest-dev-help

manifest-dev-help

manifest-dev で理解できないことや、そのように動作する理由を尋ねるための場所です。それぞれの質問には、その部分が何であり、なぜ存在するのかを答えてください。各回答は ASD-STE100 にできるだけ沿わせてください。短い文を使い、各文で扱うトピックは1つにし、意味が1つに定まる簡単な言葉を使ってください。

回答方法

1. 質問で用語が指定されている場合や、部分、ファイル、動作について尋ねられた場合は、references/GLOSSARY.md を読んでください。
2. すべての用語を尋ねられた場合は、references/GLOSSARY.md の全文を提示してください。
3. 質問がない場合は、manifest-dev の目的、ワークフロー、自律性の段階を提示してください。
4. ユーザーが何かを示している場合は、まずそれを読んでください。Manifest、ログ、プルリクエスト、ファイルなどです。
5. ユーザーのプロジェクトについての質問の場合は、そのプロジェクトの Project Surfaces も読んでください。
6. このスキルに回答やその理由が書かれていない場合は、その動作を担当するスキルを読んでください。
7. このスキルと同じフォルダーにあるスキルを探してください。その SKILL.md と references/ フォルダーを読んでください。manifest-dev-tools プラグインのスキルは、そのプラグインの skills/ フォルダーにあります。このプラグインは、このスキルとは別にインストールされています。スキル名で検索して、そのフォルダーを見つけてください。
8. 質問に対してのみ回答してください。
9. 各部分が何であるかだけでなく、存在する理由も説明してください。
10. このスキル以外のファイルに基づいて回答する場合は、そのファイル名を示してください。
11. 回答が書かれたファイルがない場合は、推測せず、そのことを伝えてください。

manifest-dev の目的

エージェントは今やほとんどすべてのコードを書けますが、それでもプロジェクトは軌道から外れていきます。セッションのたびに、プロジェクトの目的、次にすべきこと、「完了」の意味を改めて見つける必要があります。その結果、エージェントの速さによって、人が確認できる量を超える作業が生まれます。

manifest-dev は、この3つを人の頭の中ではなく、プロジェクト内に保ちます。エージェントはそれらを読み、それらに照らして作業を行い、完了を宣言する前に結果を確認します。目指すのは、複雑なタスクをエージェントに任せ、最小限のレビューで成果をリリースできるほど信頼することです。数週間後も、プロジェクトは自らの目的、次の作業、「完了」の意味を把握しています。また、コードを以前より正しく変更しやすくなります。

定めた範囲内で、プロジェクトの成果を割り当てることができます。/orchestrate は調査し、作業を組み立て、成果を届け、その結果を読み取ることができます。自分で行いたい判断は、引き続き自分で行えます。信頼できる継続的な運用は、今後の目標です。タスクを完了しただけでは、その目標を達成したことにはなりません。

manifest-dev は、信頼できる成果を求める開発者向けです。そのために、最初により多くのトークンと作業を費やすことに同意する開発者が対象です。1人でも、どのような規模のチームでも使えます。チームの同僚が manifest-dev を使わないコードベースでも利用できます。最速または最安の結果だけを求める人向けではありません。

質問	答えがある場所	その内容が維持される期間
このプロジェクトの目的は何ですか？	プロジェクト内のファイル「North Star」	権限を持つ人の裁定によって変更されるまで
次に行う作業は何ですか？	トラッカーまたはファイル内の Ticket	その作業が完了するまで
この作業の「完了」とは何ですか？	その作業に必要な、有限の Manifest	1回の実行中

ワークフロー

1. 変更を加える前に、/figure-out <topic> を使って問題を理解します。
2. /define を使ってマニフェストを作成し、完了とみなす条件を記します。
3. /do <manifest-path> を使って作業を進め、各ゲートの根拠を示します。

/auto は途中で止まらずに、この3つのステップを実行します。各スキルは単独でも使えます。また、どのプロジェクトもこの手順に従う必要はありません。Read から /ticket-up に進んでも、直接作業を割り当ててもかまいません。 あなたとエージェントの間で問題の認識がまだ一致していない場合、/define はまず /figure-out を開始します。 既存の成果物を目標に向けて段階的に改善するには、tools プラグインの /hillclimb を使います。これは同じ3つのステップを実行します。

ツールで質問を選択肢のリストとして表示できる場合、/figure-out と /define はその形式で質問します。最初の選択肢が推奨される回答です。自分の言葉で回答することもできます。

/do は、あなたが不在であるかのように動作します。委任された判断を行い、その内容を報告します。あなたが保持する判断については、あなたの対応を待ちます。/do の実行中に送信したメッセージはマニフェストを変更し、実行は続行されます。すべてのゲートに根拠が示されるか、人が対応する必要が生じたときにのみ停止します。

作業がプルリクエストに進むと、その説明には変更が機能している様子が示されます。冒頭には、何をなぜ変更したか、実行によってどのように動作を確認したか、判断事項、残された Debt が記されます。また、実行中に修正した問題も列挙されます。短い例では、変更の前後で何を行い、何が得られるかを説明します。スクリーンショットでは、目で確認できる変更を示します。

自律性の段階

manifest-dev は5つのレベルで使えます。各レベルは、それより上のレベルなしでも機能します。チームの他のメンバーがどのレベルを使う必要もありません。プロジェクトに適したレベルで止めてください。

レベル	実行すること	得られるもの	必要なもの
1. 1つのスキル	たとえば質問に対する /figure-out のように、スキルを単独で使います。	セットアップ不要で、より良い回答やレビューが得られます。	プロジェクトへの変更はありません。
2. 1つの作業	/figure-out、/define、/do、または /auto を使います。	各ゲートの根拠を伴う成果が得られます。	最初に、より多くのトークンと時間が必要です。マニフェストとそのログはリポジトリの外に保管されます。
3. Project Surfaces	/setup-project を一度実行します。	各セッションが、プロジェクトの方針、用語、判断、チェック項目を引き継いで始まります。	チームが確認できるファイルがリポジトリに追加されます。
4. 共有キュー	/ticket-up で作業を登録し、/next-ticket で取得します。	次の作業は、誰か1人の頭の中ではなく、ストアに保管されます。	Ticket Store が必要です。GitHub Issues、ファイル、または独自のトラッカーを利用できます。
5. 調整	キューまたは明示した成果を指定して /orchestrate を開始します。その計画を承認するか、選択した制限の範囲内で --autonomous を使います。	調査とデリバリーのジョブが、個別の Ticket として実行されます。結果が次の動きを導きます。保留中の判断や不足している根拠も確認できます。	割り当てに適した権限と根拠の情報源が必要です。自動的に続行したい場合に限り、既存のホストによる起動が必要です。

レベルを上げるには、次の手順に従います。

1. 現在のレベルの結果を信頼できるようになるまで使います。
2. 現在のレベルでは不十分な部分に、次のレベルを追加します。
3. 必要な判断がすべて確定または委任され、保留中の承認や不足しているアクセスがない場合にのみ、Auto を許可します。

割り当てと権限

割り当てでは、実行する作業を指定します。委任では、その作業の範囲内で作業者が下せる判断を指定します。恒常的な委任によって作業が開始されることはなく、モードフラグを設定しても権限の範囲は広がりません。

/setup-project を使って、必要な調整内容をプロジェクトの指示に記録します。個人的なルールは非公開の指示に記載してください。セットアップでは、新しい選択肢を保存する前に、提案するテキストが表示されます。操作は開始されません。

たとえば、ビジュアルの方針は委任しつつ、レンダリング結果の承認は自分に留保できます。作業者は作成して提案できますが、その承認段階ではあなたの対応を待ちます。承認が適用されるのは、該当する成果物とバージョンです。重要な変更があった場合は、改めて承認が必要です。

その他のスキル

スキル	用途
/setup-project	プロジェクトに北極星、用語集、意思決定記録の規約を設定し、オプトアウトしない限り検証ハーネスを追加します。ギャップを見つけるには、もう一度実行してください。
/ticket-up	作業をチケットとしてチケットストアに記録します。
/next-ticket	次のチケットを選択して担当し、それが最初に選ばれた理由を確認します。
/run-ticket	質問を調査するか、具体化された作業を実行し、その結果と進捗を同じチケットに記録します。
/orchestrate	ステータスページと、あなたの対応待ちの項目一覧を使って、キューまたは割り当てられた成果を調整します。
/figure-out-team	Slack のチャンネルまたはスレッドでチームとともに /figure-out の作業を行います。
/review-code	変更を品質の観点から1つ選んでレビューします。Manifest のゲートで使用されます。
/audit-state-machines	コードベース内の各ステートマシンを見つけて、モデルを使って個別に確認し、見つかったバグを提示します。コードは変更しません。
/create-principles-skill	デザインなど、特定の作業領域でチームが望む進め方をまとめたプロジェクトスキルを作成または更新します。チームがすでに共有した内容を利用します。
/review-writing	テキストをスタイル基準に照らしてレビューします。
/design	ページ、アプリ、ドキュメントなどのビジュアル制作に向けたデザインの方向性を得ます。
/review-design	対象となる媒体でデザインをレビューします。
/check-pr	プルリクエストをマージする準備ができているか確認します。マージはしません。
/manifest-dev-help	このガイドを読むか、質問します。

ツールプラグイン

manifest-dev-tools プラグインは、以下のスキルを追加します。プラグインを1つずつインストールするホストでは、こちらもインストールしてください。インストールされていない場合、これらのスキルは利用できません。

スキル	用途
/babysit-pr	オープン中のプルリクエストを、マージ可能になるまで CI、レビューコメント、競合への対応を通じて進めます。マージはしません。
/review-pr	プルリクエストをレビューし、あなたのアカウントでコメントを投稿します。
/walk-pr	エージェントと一緒に、プルリクエストまたは大規模な差分を一部ずつ確認します。
/hillclimb	既存の成果物を、目標に向けて反復的に改善します。
/prompt-engineering	プロンプト、スキル、またはエージェントを作成、変更、または検討します。
/review-prompt	プロンプトをレビューし、指摘事項を提示します。ファイルは変更しません。
/write-goal	「完了」の定義を示す短い目標を1つ作成し、目標欄に貼り付けられるようにします。
/handoff	新しいセッションまたは別のエージェントが作業を続けるために必要なコンテキストを引き継ぎます。
/teach-me	変更、プルリクエスト、またはトピックについて、段階的に学びます。
/eli5	トピックを図解付きで、とても簡単に説明します。

/review-pr は、自分では直接使わない3つのスキル、review-pr-holistic、review-pr-judgment、review-pr-thread-verify を呼び出します。

このガイドでは各スキルを /name と表記します。ホストによっては、たとえば $name や /skill:name のように異なるプレフィックスを使用できます。

各要素の関係

• Manifest には 1 つ以上の Deliverable があります。各 Deliverable には 1 つ以上の Acceptance Criteria があります。
• Global Invariants はすべての Deliverable に適用されます。Process Guidance は助言であり、拘束力はありません。
• 各 Acceptance Criterion と Global Invariant は 1 つのゲートです。ゲートには Judgment Gate と Deterministic Gate があります。
• /do は証拠を示して各ゲートに合格します。ゲートに失敗した場合、/do は作業を修正し、ゲートを再度確認します。
• プロジェクトでは、North Star、用語集、意思決定記録を管理します。検証ハーネスを管理することもできます。/setup-project でこれらを導入し、通常の実行で最新の状態に保ちます。
• 検証ハーネスには、機能、スキル、ドキュメントのウォークスルー、評価スイートごとに 1 つの Recipe があります。また、リンターやテストなど、プロジェクト全体のチェック用の Recipe もあります。/do は変更が影響する Recipe を実行します。プロジェクトではハーネスを使用せず、独自のチェックを管理することもできます。その場合、/do はそれらのチェックを使用します。
• Ticket には 1 単位の作業をまとめます。/ticket-up で作成し、/next-ticket で選択し、/run-ticket で実行します。/orchestrate は複数の Ticket を実行して取り込みます。
• 実行中にミスを修正すると、Lock が追加されます。見つけたもののプルリクエスト内で修正できない問題は Debt になります。次にそのコードを変更する実行では、Debt の修正を提案します。

この仕組みを採用する理由

• 作業を始める前に「完了」の条件を記述します。目標がなければ、エージェントは結果を目標と照らし合わせて確認できません。
• ゲートは証拠がある場合にのみ合格します。「完了」と書かれた要約が間違っていることもあります。
• /do は、あなたが不在でも作業を完了できるように動作します。あなたに代わって行った各判断を報告します。
• 修正するたびにチェックが追加されるため、同じミスが再発しません。
• 方針、用語、意思決定はリポジトリに記録されます。新しいセッションはゼロからではなく、これらをもとに始まります。
• コストのかかるチェックは事前に確認を求め、無料のチェックは頻繁に実行します。実行時間だけがコストではありません。
• 各レベルは単独で機能します。そのため、manifest-dev を使っていないチームに所属していても、途中から導入できます。

推奨される方法

• 実際の問題について /figure-out から始めます。質問する前にコードを読ませてください。
• /do が始まる前に、Outcome とゲートを読みます。変更できない条件と、エージェントが変更できる条件を確認してください。
• 小さな問題は /do に発見して修正させます。そのために処理を止めないでください。
• 方針の変更は /do へのメッセージとして伝え、Manifest に反映させます。実行中に自分でコードを変更しないでください。
• 要約ではなく、証拠を信頼してください。
• コストのかかるチェックを実行する前に承認してください。ask-first マークの付いた Recipe は、費用、クォータ、または共有システムへの負荷が発生します。
• /setup-project を 1 回実行して Project Surfaces を導入します。
• 修正するたびにチェックを追加し、後から作業する人にも同じミスが検出されるようにします。
• 各プルリクエストの「Debt left」セクションを読みます。次にそのコードを変更するときに Debt を修正してください。
• 最初は、より多くのトークンと作業が必要になることを想定してください。その代わり、ただ信頼するだけでなく、内容を確認できる結果が得られます。