依頼文には、指一本触れていない。
それでも、結果は正反対になった。
1. 「提示情報のみでは確認できません」
設計文書への反映作業で、対象箇所を特定するための調査をTAKTへ依頼したときのことである。読み取り専用の依頼であり、対象の設計文書も実装ファイルも、すべて手元にあった。
しかし、返ってきたのは調査結果ではなかった。
提示情報のみでは確認できません。
TAKTは、依頼文に書かれた文章だけを読み、設計文書も実装ファイルも一度も開かないまま、この一文だけを返して終了した。
最初は、依頼文の書き方が悪かったのだと思った。
調査観点が曖昧だったのか。参照範囲の指定が弱かったのか。あるいは、読み取り専用であることを強調しすぎたせいで、ファイル確認まで止まってしまったのか。
いくつかの可能性を考えたが、最終的に原因は別の場所にあった。
問題は、依頼文ではなかった。
選んでいたワークフローだった。
2. 同じ依頼文のまま、ワークフローだけを変えた
依頼文を書き直す前に、まずワークフローの選択を疑った。
このときTAKTへ渡していたのは、build-stepだった。
そこで、ワークフローをresearchへ変更した。依頼文は一字も変えていない。設定も同じである。ただ、選ぶワークフローだけを変えて、同じ依頼を再投入した。
結果は一変した。
TAKTは実際にファイルを読み、grep・sedを使った実測に基づく調査結果を返してきた。必要なAPIは既存のレスポンスをそのまま使えること、権限の判定が特定の1箇所に集約されており、全ロールへ自動的に適用されることまで、具体的な行を示して報告した。
依頼文は同じである。
設定も同じである。
変わったのは、選んだワークフローだけだった。
この時点で、原因の場所がはっきりした。
依頼文の表現ではなく、依頼を渡す「入れ物」が合っていなかったのである。
3. build-stepとresearchは、前提が違う
build-stepとresearchは、見た目には似ている。
どちらもTAKTへ作業を依頼するためのワークフローであり、どちらも実装や調査の前段で使えそうに見える。
しかし、そもそもの立ち位置が違う。
researchは、TAKTに標準で組み込まれているワークフローである。公式のビルトインカタログに「質問せずに自律的に調査を実行する」ためのものとして、最初から用意されている。
一方、build-stepは、こちらで独自に作ったワークフローである。TAKTの標準には存在しない。実装作業に合わせて、必要な形へカスタマイズしたものだった。
つまり今回の一件は、標準品と自作品を比べていたのではない。標準の調査用ワークフローがあるにもかかわらず、それを使わずに、自作の実装用ワークフローへ調査を依頼していた、ということになる。
前提の違いは、こうなる。
build-step |
research |
|
|---|---|---|
| 主な目的 | 成果物の生成・修正 | 情報の収集・調査 |
| 想定する状態 | これから実装することが決まっている | 何を実装すべきかを、これから調べる |
| 情報不足のときの動き | 判断できず終了することがある | 分かったこと、分からなかったことを報告する |
build-stepは、実装する対象がすでに定まっていることを前提にした構成になっている。「何を直すか」「どこを変更するか」がある程度決まっており、その作業を進めるためのワークフローである。
一方、researchは、まだ答えが定まっていない段階で使う。どこを見ればよいのか、どのファイルが関係するのか、何が不足しているのかを調べるためのワークフローである。
この違いは、実務上かなり大きい。
特に大きいのは、情報不足のときの返し方である。
researchは、すべての観点に答えを出せなかった場合でも、分かった範囲と分からなかった範囲を分けて報告できる。
一方、build-stepは、この中間的な返し方をあまり想定していない。ひとつでも判断できない要素があると、全体を「情報不足」としてまとめて終わらせてしまうことがある。
つまり、調査を依頼しているつもりでも、build-stepへ渡してしまうと、TAKT側では「実装できるだけの情報が揃っていない」と判断されることがある。
その結果、手元に読むべきファイルがあるにもかかわらず、ファイルを開く前に止まってしまう。
4. 「判断できません」で止まる仕組みは、もともと安全弁だった
では、なぜbuild-stepは情報不足のときに止まるのか。
これは、単なる不具合として生まれたものではない。
もともとは、逆方向の失敗を防ぐための安全弁だった。
以前、TAKTが「判断できない」「情報不足」という結果を出した後も、セッションが終了せず、runningの状態で残り続けることがあった。見た目には回答が返ってきているため、一見すると完了しているように見える。
しかし、内部ではプロセスが終わっていない。
次の作業に進もうとして初めて、まだ止まっていないことに気づく。気づかず放置すれば、無駄な待ち時間が積み重なっていく。
この問題を避けるため、build-step・test-step・doc-genでは、判断できないときにループし続けるのではなく、「実装未着手（レポートのみ）」として正常終了できる分岐を組み込んだ。
つまり、この仕組みは「情報が足りないまま誤った報告をする」ことを防ぐためではない。
「情報が足りないまま、いつまでも終わらなくなる」ことを防ぐために作られた。
止まれること自体は、必要な設計だった。
ただし今回は、その安全弁が効きすぎていた。
本来はファイルを読んで調査すべき場面でも、build-stepの前提に引っ張られ、調査に入る前に「判断できません」で止まってしまったのである。
5. 「情報不足」には2種類ある
ここで注意したいのは、「情報不足」という回答そのものが、常に誤りではないということだ。
情報不足には、少なくとも2種類ある。
ひとつは、本当に確認手段がない場合である。
たとえば、実データの確認を依頼したとき、対象環境にpsqlコマンドもdockerコマンドも存在せず、データベースへ接続するための環境変数も設定されていないことがあった。
この場合、TAKTは実行すべきSQL文を提示したうえで、「この実行環境ではDBへ接続できず、実データの確認は未実施」「情報不足であり、判断できない」と報告した。
これは適切な振る舞いである。
存在しない接続手段を、存在するかのように装って進めなかったからである。
もうひとつは、手元に確認できる情報があるのに、それを見に行かない場合である。
今回問題にしているのは、こちらである。
設計文書も実装ファイルも手元にある。読み取り専用の依頼であり、確認すべき観点も指定している。それにもかかわらず、ファイルを一度も開かずに「提示情報のみでは確認できません」と返ってくる。
これは、単なる情報不足ではない。
確認できる材料を確認しないまま、情報不足として終わっている。
この2つを混同すると、対処を誤る。
本当に確認手段がない場合は、環境を整えるしかない。ワークフローを変えても、存在しないDB接続手段が急に現れるわけではない。
一方、確認できる材料があるのに見に行かない場合は、ワークフロー選択で解決することがある。
今回の事例は、まさに後者だった。
6. 同じ上限値でも、効き方が違う
自作した3つのワークフロー（build-step・test-step・doc-gen）には、いずれもmax_steps: 10という同じ値を設定している。1回の実行が進められるステップ数の上限であり、セッションの消費を抑えるために入れたものである。
ただし、同じ10という数字でも、効き方はワークフローによって違う。
doc-genは、実装（この場合は文書生成）を行う単一のステップだけで構成されている。完了するか、完了せずにレポートのみで終わるかのどちらかで、そこから先の往復は無い。1〜2ステップで完結するため、10という上限はほとんど意味を持たない。ドキュメントのみを対象にした、判断を伴わない単純な作業に限定して使っているのは、そのためである。
一方、build-step・test-stepは、実装したものをレビューし、必要なら修正し、また確認するという往復を含む構成になっている。ここでの10は、その往復が際限なく続かないようにする、実質的な歯止めとして機能する。
同じ数字を置いても、構造の違いによって、実際に働くかどうかが変わる。設定値だけを見ても、その仕組みが何を制御しているかは分からない。
7. 依頼文を直す前に、ワークフローを疑う
振り返ると、これまでは同じような現象に対して、依頼文側の対処を重ねてきた。
冒頭に「ツール使用は禁止されていない」旨を明示する。「本ラウンドの前提」という節を新設し、参照範囲を限定する。書式を調整し、それでも改善しなければ実行環境側の設定を疑う。
いずれも、渡す文章そのものに手を加える対処だった。
効くこともあった。
しかし、効かないこともあった。
今回、依頼文をまったく変えずにワークフローだけを切り替えたところ、症状が消えた。
これによって、少なくとも一部のケースでは、原因が依頼文の外にあることが分かった。
TAKTの回答が「提示情報のみでは確認できない」「判断できない」「情報不足」といった内容に終始する場合、すぐに依頼文を書き直すのではなく、まずワークフロー選択を確認した方がよい。
特に、依頼内容が調査であるにもかかわらずbuild-stepを選んでいる場合は、researchへ切り替えるだけで動きが変わる可能性がある。
8. 課題管理表に出てこなかった理由
この種の問題が、課題管理表に紛れ込んでいないかも確認した。
結果として、該当する記録はなかった。
課題管理表には、プロダクト側の不具合や機能要望が並んでいる。一方で、TAKTのワークフロー選択や実行環境の設定に関する気づきは、引き継ぎ資料側の教訓として別に管理されていた。
つまり、「ユーザーに見えるプロダクトの課題」と「開発の進め方そのものの課題」は、自然に別の場所へ分かれていた。
この区分けは、後から見ると都合が良かった。
もし両方が同じ表に並んでいたら、プロダクトの課題なのか、開発運用の課題なのかを、毎回切り分ける必要があったはずである。
今回の件は、プロダクトの不具合というより、開発作業の進め方に関する教訓である。
そのため、課題管理表ではなく、運用上の学びとして扱う方が自然だった。
9. 現在の使い分け
以上を踏まえて、現在の使い分けはシンプルになった。
調査が目的なら、researchを選ぶ。分からない点が残っても、分かった範囲と分からなかった範囲を分けて報告してくれる。
確定済みの処理を実行するだけなら、build-stepでよい。実際、内容が確定しているPythonスクリプトを実行するだけの場面では、build-stepは問題なく機能している。
そして、TAKTの回答が「判断できない」「情報不足」に終始する場合は、依頼文を直す前に、まずワークフロー選択を確認する。
特に重要なのは、次の切り分けである。
確認手段が本当にないのか。それとも、確認できる材料があるのに見に行っていないのか。
前者であれば、環境を整える必要がある。後者であれば、ワークフローを選び直すことで解決する可能性がある。
10. まとめ——中身を直す前に、入れ物を疑う
今回分かったのは、依頼文をどれだけ整えても直らない現象があるということだった。
もちろん、依頼文の書き方は重要である。何を調べるのか、どのファイルを参照するのか、どこまでが読み取り専用なのかを明確にすることには意味がある。
しかし、依頼文だけでは解決しないこともある。
今回のように、依頼文は同じでも、build-stepからresearchへ変えただけで結果が正反対になることがある。
これは、文章の問題ではなく、ワークフローの前提の問題である。
build-stepは、実装対象が定まっている前提で動く。researchは、これから情報を集める前提で動く。
調査を依頼しているのに、実装前提の入れ物に入れてしまうと、TAKTは調査へ進む前に止まってしまうことがある。
同じ「情報不足」という言葉が返ってきても、原因はひとつではない。
本当に確認手段がない場合もあれば、確認できる材料があるのに、ワークフローの選択によって見に行けていない場合もある。
原因の場所が違えば、効く対処も違う。
依頼文を直す前に、入れ物を疑う。
今回の一件は、その重要性を確認するための記録である。同じTAKTの運用でも、依存関係の脆弱性対応では、サンドボックスが外部ネットワークへ出られないという、また別の環境側の制約に行き当たっている。原因の場所を切り分ける作業は、形を変えて繰り返し必要になる。
動画作成には自信があります！
