要件定義からコードまで：トレーサブルなAIエージェントワークフロー

エージェント導入が静かに失敗するのは、「要件からコードへ」の段階だ。エージェントが書いたコードが悪かったわけではない。問題は、6週間後に、ある変更がどの要件から生まれたのか、誰がスコープを承認したのか、レビュー担当者が受け入れる前にどんな根拠を見たのかを、誰も示せないことにある。コードはすぐに届いた。記録は届かなかった。

このチュートリアルでは、その記録を意図的に作り上げる。書き留めた要件からマージ済みのプルリクエストまでを一本の鎖でつなぎ、そのどの段階も開いて確認できるようにする。GitHub の Spec Kit は、リポジトリ内のファイルで同じ課題を解決する。本ガイドはそれをワークシステムで解決する。ここで Sharkly を使うのは、鎖の全体を1つのタスク上に保持できるからだが、同じリンクを保持できるトラッカーならどれでもこのパターンは応用できる。まず運用ループを知りたい場合は、AIエージェントプロジェクト管理のガイドから始めてほしい。

TL;DR

追跡可能な要件からコードへのワークフローとは、すべての成果物が、それを生み出した成果物を指している状態をいう。要件、タスク、サブタスク、実行、プルリクエスト、受け入れ。Sharkly では、要件がタスクになり、エージェントがプランモードで分解案を提示し、人がそれを確認する。各サブタスクは実行ログ付きの分離されたワークツリーで実行され、プルリクエストはタスクIDでリンクし、最後に人が当初に書いた受け入れ基準に照らして成果を受け入れる。エージェントは調査し、実行し、テストし、報告する。人は方向性を定め、権限を与え、成果を受け入れる。

「追跡可能」が意味すべきこと

トレーサビリティとは、最後に生成するレポートのことではない。鎖の性質そのものだ。各リンクは直前のリンクがあるからこそ存在し、どちらの方向にもたどれる。機能1つは6つの段階でカバーできる。

どれか1つでも欠けていれば、その鎖は飾りにすぎない。最もよくある欠落は最後の段階だ。つまり、変更を要件と照合した人が誰もいないのに、マージ済みのプルリクエストを受け入れと見なしてしまうケースである。

ステップ1: 要件をタスクとして書く

タスクは Sharkly で追跡される作業の基本単位であり、ソフトウェア開発用にセットアップされたスペースには、最初から Requirement、Bug、Task、User Story のタスクタイプが用意されている。親には Requirement または User Story を使う。タイプによって適用されるカスタムフィールドとワークフローステータスが決まるため、Requirement は Bug のワークフローを汚すことなく、独自のレビューステータスを持てる。

説明文が要となる。その会話を見ていない人に向けて書く。作業がなぜ重要か、何がスコープ内で何がスコープ外か、関連するファイルや観察された挙動、すでに下された決定、そして完了をどうレビューするか。この最後の項目が受け入れ基準であり、6つ目の段階のアンカーになる。まだ書けないなら、その要件は準備ができていない。まさにそのためのバックログだ。エージェントにアサインされたタスクも、バックログにある間は開始されない。

リポジトリはスペースレベルでアタッチし、すべてのサブタスクがそれを継承するようにする。リポジトリが何も紐付いていないエージェントは、スペースの Git リポジトリにフォールバックする。複数タスクにまたがる機能ではこれが望ましい。

ステップ2: エージェントに分解をまとめさせ、それを確認する

タスクのエージェントチャットを開き、セッションをプランモードに切り替える。プランモードでは、エージェントがあなたのレビュー用にアクションを提案でき、Sharkly は提案を確認した後にのみ、計画されたタスクとサブタスクを作成する。開始せずに確認することも、確認して作業を開始することもできる。

ここは多くのチームが飛ばす段階であり、分解をその場しのぎではなく追跡可能にするポイントでもある。提案は作業になる前に目に見える。スコープを広げるサブタスクを削り、エージェントが見落としたマイグレーション手順を追加できる。サブタスクは親と同じスペースに留まり、Sharkly は自己親子関係や循環を拒否するので、階層はツリーのまま保たれる。

1つの役割でカバーできる要件には、単一のエージェントを使う。リーダーが目標を解釈し、テスト作成者などの他のエージェントメンバーを巻き込み、その結果を1つのタスクに持ち帰る必要がある場合は、クルーを使う。3ファイルの変更なら、クルーは可動部を増やすだけで、追跡可能性は高まらない。Sharkly Crews のガイドで、リーダー主導モデルを解説している。

チャットで決まったことは何でもタスクの説明にコピーする。タスク上のチャットはコメントではなく、アクティビティにも表示されない。そのため、そこにしか存在しない決定は、鎖からは見えない。

ステップ3: 痕跡を残しながら分離環境で実行する

各サブタスクを担当者コントロールからエージェントにアサインし、バックログから出す。Sharkly はステータスカテゴリと実行準備状況を確認し、実行をキューに入れ、選択されたコンピュータにディスパッチする。そこでローカルサービスが分離されたタスクディレクトリを用意し、ランタイムを起動する。

この段階を確かなものにする詳細が2つある。実行にはタスクのタイトルと説明、最近のコメント、許可されたステータスを含むタスクタイプのワークフローが含まれるため、エージェントは言い換えではなく要件に基づいて作業する。そして、リポジトリに紐づく各実行はテンポラリモードで独自のワークツリーを取得するので、並行するサブタスクが互いを上書きすることはない。マージコンフリクトなしでエージェントを並行実行する方法の記事で、分離がなぜファンアウトを安全にするのかを説明している。

進捗、トレースイベント、結果はタスクに返る。実行ログには、実行がなぜキューに入ったか、いつ開始・終了したか、ツール呼び出しとランタイムイベント、トリガー元、失敗の詳細が記録される。このログが4つ目の段階だ。

ステップ4: IDでプルリクエストをリンクする

GitHub 組織を一度接続し、タスクIDをプルリクエストのタイトル、説明、またはソースブランチ名に入れる。SH-312 だけでも Fixes SH-312 でもリンクは作成される。リンクバックはプルリクエストにタスクURLをコメントする。プライベートリポジトリではデフォルトで有効だ。

ここで境界線を明確にしておく。追跡可能性にとって重要な点だ。fixes や closes といった言葉に特別な意味はなく、プルリクエストをマージしてもタスクのステータスは変わらない。Sharkly は変更をタスクにリンクするだけで、タスクが完了したとは判断しない。ステータスは人の判断のままであり、それが6つ目の段階の要点である。Jira チケットをAIエージェントにアサインしてPRを受け取るまでのウォークスルーでは、トラッカー側からの同じリンクを紹介している。

ステップ5: 要件に照らしてレビューし、受け入れる

エージェントはタスクを人のレビュー待ちにできる。そのシグナルは担当者の受信トレイの Primary に届く。3つを順に読む。ステップ1の受け入れ基準、エージェントが実行したチェックと不確実な点を列挙したコメント、そして実行ログ。diff を見るのはそのあとだ。

別のテストタスクが変更を検証する場合は、その関係を明示的に記録する。組織のオーナーと管理者はカスタムリンクタイプを作成でき、ドキュメントにある例の validates / is validated by が、この段階の追跡可能性のエッジとなる。リレーションはそれ自体ではステータスを変えないため、受け入れはやはり人によるステータス変更でなければならない。

ここで役立つカテゴリのルールが1つある。タスクを Completed に移動すると終端状態にはなるが、すでにアクティブな実行はキャンセルされない。エージェントがまだ作業中の場合は、先にキャンセルしてから判断する。

鎖が途切れる場所

上記のワークフローには3つの既知の断点があり、率直に述べておく価値がある。

結論がチャットに置き去りにされる。 単独のエージェントチャットセッションは、作成した個人に属する。そこで設計が固まったとしても、タスクはそれを知らない。

タスクの外で実行が開始される。 オートメーションワークフローの Run Agent アクションはタスクを作成しない。実行はエージェントに記録される。夜間チェックなら問題ないが、機能開発では間違いだ。

記録の代わりにファイルを使う。 Spec Kit の spec.md、plan.md、tasks.md は、1人の開発者が1つのリポジトリで作業する場合には強力な鎖になる。チームが自分一人ならこれを使えばいい。2人目がレビューしたり受け入れたり、あなたのチェックアウトを開かずに何が起きたかを確認したりする必要があるなら、共有のワークシステムを使う。Sharkly は Claude Code や Codex などの実行ツールの置き換えではない。それらを取り巻く鎖を見える状態に保つレイヤーだ。各概念の詳細は docs.sharkly.ai で解説している。

FAQ

「要件からコードへ」とは、エージェントが要件を書くという意味ですか？ いいえ。要件とその受け入れ基準は人が書きます。エージェントはコードベースを調査し、プランモードで分解案を提示できますが、その提案がタスクになるのは、人が確認した後だけです。

要件を Jira に置いたまま、トレースも得られますか？ はい。Jira のインポートと同期により、組織が読むトラッカーをそのまま使いながら、Sharkly が実行記録を保持します。人とエージェントのチーム向け Jira 代替の記事では、トラッカー自体の置き換えを検討しているケースを扱っています。

レビュー前にプルリクエストがマージされたらどうなりますか？ タスクのステータスは変わらないため、鎖にはマージ済みの変更を持つ未受け入れのタスクが表示されます。これは正しいシグナルです。まだ人が判断を下す必要があります。

最初の追跡可能な機能はどのくらい小さくすべきですか？ 要件1つ、サブタスク2〜3個、エージェント1体です。Claude Code プロジェクト管理のウォークスルーでは、1つのタスクでループを端から端まで実行します。