tk3.biz
ブログ一覧に戻る

dev-orchestra に、設計の前に質問させてみた

はじめに

AI に「タスクに期限を付けられるようにして」とだけ頼むと、どんな機能ができるでしょうか。期限は追加するときに付けるのか、あとから付けるのか。日付だけか、時刻も入れるのか。一覧は期限の順に並べるのか。

頼んだ側が決めていないことは、AI が黙って決めて計画を書きます。たいていは妥当な決め方です。でも、できあがってから「そうじゃなかった」と気づくこともあります。

dev-orchestra には、1.1.0 から、設計の前に決まっていない点を聞かせる機能(design.ask_questions)があります。今回はこれを試しました。いちばん意外だったのは、自分では「はっきり頼んだ」つもりの依頼でも、決めていない点が 4 つ見つかったことです。

dev-orchestra は、1 文の依頼から設計・実装・テスト・複数の AI によるレビュー・修正までを回す、Claude Code / Codex / Antigravity のプラグインです。前回は、複数の AI の指摘をトリアージして、修正役に直させました。

dev-orchestra は GitHub で公開しています(MIT ライセンス)。役に立ちそうと思ったら、スターを付けてもらえるとうれしいです。

→ github.com/istb16/dev-orchestra

試した条件

設定は auto と true の 2 つを試しました。既定は false(聞かない)です。auto は、依頼があいまいなときだけ聞きます。true は、アーキテクト(設計役)がコードを読んで質問するラウンドを、毎回必ず挟みます。

dev-orchestra config set design.ask_questions auto
項目内容
dev-orchestra1.3.0、プリセット standard
呼び出し元Claude Code 2.1.312。claude -p で依頼し、答えは claude -p --resume で渡した
アーキテクトClaude Fable
題材作業用に作った小さな Python のパッケージ todo(タスクを JSON に保存する Store と、add・done・list の CLI、テスト 2 件)
環境Windows 11、Python 3.14.7。設定は普段とは別のフォルダ(DEV_ORCHESTRA_HOME)に置いた

依頼は、あいまいなものと、はっきりしたものの 2 つです。

  • あいまいな依頼は「タスクに期限を付けられるようにして。」
  • はっきりした依頼は「Store に rename(task_id, title) を追加して。存在しない ID なら KeyError を送出する。CLI に『todo rename <id> <title>』を足し、README とテストも更新して。」

あいまいな依頼は auto で、はっきりした依頼は auto と true の両方で頼みました。どれも、計画の承認を求められたところで止めています。

あいまいな依頼では、3 つ聞かれた

「タスクに期限を付けられるようにして。」を auto で頼むと、設計に入る前に止まって、3 つ質問してきました(1 分 6 秒)。

「期限」の仕様は読み方によって作るコードが変わるため、設計の前に 3 点確認させてください(`Q1`〜`Q3` として記録済み)。

**Q1. 期限をどう設定するか**
- A: 追加するときだけ指定する — `todo add buy milk --due 2026-11-01`
- B: 既存タスクに別コマンドで設定する — `todo due 1 2026-11-01`
- C: A と B の両方(B のコマンドで変更・解除もできる)
- **推奨: C** — この変更より前に作ったタスクにも期限を付けられ、間違えた期限も直せるため

**Q2. 受け付ける日付の形式**
- A: 日付のみ `YYYY-MM-DD`
- B: 日付に加えて時刻も任意で `YYYY-MM-DD[ HH:MM]`
- C: `YYYY-MM-DD` に加えて `today` / `tomorrow` などの相対指定
- **推奨: A** — 最も単純で曖昧さがなく、`todo.json` に ISO 形式の文字列で保存できるため

**Q3. `todo list` での表示**
- A: タイトルの横に期限を表示し、並び順は今まで通り(id 順)
- B: 期限を表示し、期限順に並べる(期限なしは最後)
- C: B に加えて、期限切れのタスクに `(overdue)` などの印を付ける
- **推奨: C** — 期限は「次に何をやるか」「何が遅れているか」を見るのに役立つため

冒頭で私が並べた迷いどころが、ほぼそのまま聞かれました。選択肢と推奨が付いているので、答えるのに手間はかかりません。私はこう返しました。

Q1 は C。Q2 は「YYYY-MM-DD の日付だけ。過去の日付も受け付ける」。Q3 はお任せします。

答えるまでは、計画は書かれません。計画を書くコマンドを自分で走らせても、モデルを呼ぶ前に止まりました(--force でも越えられません)。

$ dev-orchestra run architect --prompt-file request.md --output .ai/plan.md
refusing to run architect: 3 design question(s) still open (Q1, Q2, Q3) (design.ask_questions).
Ask the user; record their words with `dev-orchestra design questions answer <ID> --option <key>` or `--text "..."`, or `--delegate` when they leave it to the architect.
Never answer for the user. Exit 6.

答えたあとの計画には ## Decisions の節ができて、誰が決めたかが分けて書かれていました(抜粋)。

## Decisions
- **Q1 (user): both `add --due` and a `due` command** that sets, changes or clears. ...
- **Q2 (user): strict `YYYY-MM-DD` only, past dates accepted.** ...
- **Q3 (me): Option C, sort by due date with undated last and mark overdue.** ...
- **Clear syntax is an explicit `--clear` (me).** ...
- **Unknown id in `due` is an error, exit 1 (me).** ...

(user) は私が、(me) はアーキテクトが決めたことです。任せた Q3 は、推奨どおり C になりました。質問に出なかった細かい点(期限を消す書き方、存在しない ID のときの終了コードなど)は、アーキテクトが決めています。

はっきり頼んだつもりでも、4 つ聞かれた

次は、rename を足す依頼です。仕様は全部書いたつもりでした。

auto では、質問は来ませんでした。依頼に仕様が書いてあるので、聞くことはないと判断したようです。

true にすると、アーキテクトがコードを読んだうえで、4 つ聞いてきました(55 秒)。質問の前には、こう書いてありました。

The code settles most of the mechanics: title joining from argv, usage docstring and README updates, `Store` already exported, KeyError test via assertRaises, and no argument validation anywhere in the CLI. Four decisions remain for you.

コードを読めばわかることは聞かず、決めなければならないことだけを聞いてきます。4 つの質問を、auto のときにアーキテクトが自分で決めた中身と並べると、こうなりました。

質問true で私が答えたことauto でアーキテクトが決めたこと
CLI で存在しない ID のときstderr に no task <id>、終了コード 1(推奨のまま)同じ
Store.rename の戻り値任せた → None(complete() に合わせる)更新後の Task(add() に合わせる)
成功したときの CLI の出力任せた → 何も出さない(done に合わせる)renamed <id> を出す
空のタイトル「空白だけのタイトルも空と同じに扱い、rename では弾く。add は今のままでいい」受け付ける(add に合わせる)

言われてみれば、空のタイトルをどうするかは考えていませんでした。auto でのアーキテクトの決め方も、どれも筋は通っています。ただ、同じ依頼でも、決め方が 2 通りに分かれました。

面白かったのは、空のタイトルの扱いです。auto の実行では、設計レビューのレビュアーが「拒否すべき」と指摘していました。オーケストレーターは「add と合わせる」として、それを採用していません。仕様として決めるべきことを、レビューの指摘の仕分けで決めていたことになります。true では、それを私が最初に決められました。

なお、戻り値と成功したときの出力は、true でも私が任せた点です。この 2 つが違ったのは、質問したからではなく、実行ごとにアーキテクトの判断が変わったからです。私が自分で決めて変わったのは、空のタイトルだけでした。

デメリットも書いておく

  • 1 往復ぶん時間がかかります。あいまいな依頼で質問が来るまで 1 分 6 秒、true のアーキテクトの質問のラウンドが 55 秒(API 料金換算で $0.34)でした。質問が来たら答えるまで止まるので、席を外していると、そのぶん遅れます
  • はっきりした依頼では、auto でも十分なことが多いです。毎回 true にすると、どうでもよい点まで聞かれることがあります
  • 答えるのは自分です。今回は 4 つのうち 2 つを「任せる」にしましたが、全部任せるなら、聞かせる意味は薄くなります

まとめ

  • あいまいな依頼が多いなら auto で足りる。はっきり頼んだつもりでも決めていない点は残るので、そこまで自分で決めたいなら true が向いている
  • 答えるのが面倒なら「任せる」でもよい。任せた点は、計画の ## Decisions の (me) の行で確かめられる
  • 決めたことを渡すと設計レビューがどれだけ変わるかは、今回の試し方ではわからなかった

次回(2026 年 11 月 23 日公開予定)は、トークンとコストを抑える方法を試します。

細かな仕様

ここからは、使うときに知っておくと安心な細かい点です。全体は資料の「Design の質問」にあります。

設定の値と、質問の 2 段階

値動き
false(既定)聞かない。アーキテクトが決めて計画を書く
autoオーケストレーター(呼び出し元の Claude Code など)が、依頼があいまい・新しい仕様・やり方が複数ある、と判断したときだけ聞く
true毎回聞く。アーキテクトがコードを読んで質問するラウンドを必ず 1 回挟む(オーケストレーターも、聞くことがあれば先に聞く)

質問は 2 段階あります。1 段目は、オーケストレーターによる要件の質問です。「何を作りたいか」はコードを読んでもわからないので、ユーザーに聞きます。2 段目は、run architect --questions でのアーキテクトの質問です。コードを読んだうえで、計画が左右される点だけを聞き、このときは計画を書きません。auto では、2 段目は必須ではありません。今回のあいまいな依頼でも、オーケストレーターの質問だけで済んでいました。

答えの記録

質問は design questions record で記録され、Q1、Q2 … と番号が付きます。答えは design questions answer で、選んだ選択肢(--option)、自分の言葉(--text)、「任せる」(--delegate)の 3 通りで記録します。最初の実行では、オーケストレーターが私の答えをこう記録しました。

dev-orchestra design questions answer Q1 --option C
dev-orchestra design questions answer Q2 --text "YYYY-MM-DD の日付だけ。過去の日付も受け付ける"
dev-orchestra design questions answer Q3 --delegate

記録された答えは decisions.md に書き出されます。質問のファイルは英語で記録されていました。オーケストレーターが、アーキテクトに渡す用に英語で書いたようです(私に見せた質問は日本語でした)。

- Answer: C: Both of the above (the separate command can also change or clear it)
- Answer: YYYY-MM-DD の日付だけ。過去の日付も受け付ける
- Answer: left to the architect

質問が残っているあいだは、status にもそう出ます。

Design questions: 3 open of 3 (Q1, Q2, Q3), round 0/2 -- ask the user; the plan run is refused until they are answered

設計レビューへの渡し方

決めたことは、設計レビューのレビュアーにも前提として渡ります。レビュアーは、計画が決めたことに従っている点を指摘しません。決めたこと自体がおかしいと思ったときは Category: decision の指摘として返し、オーケストレーターはそれを自分で採否せずにユーザーに聞きます。

答えを記録した 2 つの実行では、設計レビューが 2 回ずつ走りましたが、Category: decision の指摘は出ませんでした。決めたことと食い違う指摘も出ていません。ただ、決めたことを渡さない場合と比べてはいないので、どれだけ効いたかはわかりません。

承認のあとで答えを変えると

計画を承認したあとで答えを変えると、承認は古くなります。true の実行で、CLI の design approve で承認してから、Q3(成功したときの出力)の答えを変えてみました。答えを変えるには --revise が要ります。

$ dev-orchestra design questions answer Q3 --option B
Q3 is already answered; pass --revise to change the answer
$ dev-orchestra design questions answer Q3 --option B --revise
Q3: B: Print `renamed <id>`, following the `added <id>` pattern from `add`.
$ dev-orchestra status
...
Plan approval: stale -- a recorded decision changed after the plan was approved; revise the plan and ask again ...

status --json では、stale_reason が decisions-changed になります。計画が変わっていなくても、前提が変わったので承認し直し、ということです。前の答えは質問の履歴に残ります。

質問の回数の上限

アーキテクトの質問のラウンドは、既定で 2 回まで(design.max_question_rounds)です。モデルを呼ばずに確かめるため、「質問なし」のラウンドを手で 3 回記録してみました。

$ dev-orchestra design questions record --by architect --file no-questions.md
recorded architect round 1 with no questions in .ai/workflows/capdemo/decisions.md
$ dev-orchestra design questions record --by architect --file no-questions.md
recorded architect round 2 with no questions in .ai/workflows/capdemo/decisions.md
$ dev-orchestra design questions record --by architect --file no-questions.md
refusing to record another architect round: round cap reached (2 of 2, design.max_question_rounds): present the open points together and ask how to proceed.
Pass --force for one more round only when the user asks for it. Exit 6.

質問のラウンドを走らせる回数には、計画を書く回数とは別の予算(budgets.architect_questions、既定 3)もあります。質問を繰り返して止まらなくなることはありません。

人が見ていない実行では

計画の承認を切っている(design.require_approval: false)実行は、人が見ていない前提です。このときは、質問は記録されますが、答えを待ちません。残った質問はアーキテクトに任せて進みます。アーキテクトに mock のプロバイダを当てて、モデルを呼ばずに確かめました。

note: design.require_approval is false, so nobody is there to answer: Q1 left to the architect (recorded in .ai/workflows/capdemo/decisions.md)

decisions.md には left to the architect: nobody was there to answer (design.require_approval is false) と残るので、あとから「聞かれていたが誰も答えなかった」点を見返せます。

GitHub: istb16/dev-orchestra(スターを付けてもらえると励みになります)

この連載の記事は、「dev-orchestra」の一覧でまとめて読めます。

関連記事