plans/workbenchをdefinition/jobsに変えることになった話

Posted at 2026-10-03

前回の記事では、AIレビューで見つかった指摘をすべてその場で直すのではなく、Defer や Observe として「あとで再考する」仕組みを入れました。

さらに、レビューから得た知見そのものをKnowledge Baseとして再利用しようとしましたが、過去の知見が現在の設計authorityにまで影響し始めたため撤回しました。

そこで残ったのが、

知識を何でも覚えさせるのではなく、「あとで扱う仕事」を適切に残せればいいのでは？

という考えでした。

その置き場として使っていたのが workbench/ です。

ただ、ここで新しい違和感が出てきました。

もう、ここに置いているものは「workbench」と呼ぶものではないのでは？

今回は、そこからAIDD Skeletonのディレクトリ構成を、

plans/      → definition/
workbench/  → jobs/

へ変更した経緯を書きます。

`workbench/` が実態に合わなくなった

もともとの workbench/ は、名前どおり作業台に近い場所でした。

workbench/
  調査メモ
  アイデア
  一時的な検証
  試作

ところが実運用を続けると、そこには、

あとで再考するレビュー指摘
継続中の作業
セッションをまたぐ仕事
handoff対象
再開条件を持つ作業

まで置くようになりました。

もはや中心にあるのは「作業材料」ではなく、現在または将来扱う仕事そのものです。

そこで workbench/ の名前を見直し、最終的にかなり単純な、

jobs/

へ変えることにしました。

正式な要件や設計を置く場所でも、単なるメモ置き場でもない。

やるべき仕事、進行中の仕事、あとで再開する仕事を扱う場所。

なら、jobs が一番素直でした。

`jobs/` にしたら、今度は `plans/` が変に見えた

ところが、

plans/
jobs/

と並べると、今度は別の違和感が出ます。

名前だけ見ると、

plans = これからやること
jobs  = 実際にやること

のように見えます。

でも実際の plans/ にあったのは、

requirements
design
testing
adopted decisions

などです。

これは単なる予定ではありません。

採用済みの、

「このプロジェクトはどうあるべきか」

を表す情報です。

そこで plans/ も見直し、

definition/

へ変更することにしました。

結果として、

definition/
  何を作るのか
  どうあるべきか

jobs/
  今何をするのか
  何が途中なのか
  何をあとで再開するのか

という分離になります。

「計画と作業」ではなく、**「定義と仕事」**です。

まずは名前だけ変えた

この変更が次のコミットです。

commit 61bc922
docs: rename plans and workbench domains

対応するPRはPR #37です。

ここでは、あえて大きな意味変更を混ぜませんでした。

まず、

plans      → definition
workbench  → jobs

というrenameだけを行い、その後でそれぞれの責務を整理しました。

ディレクトリ名変更と規約変更を一度にやると、Consumerで問題が出たときに、

renameで壊れたのか
新しい規約で壊れたのか

が分かりにくくなるためです。

名前を変えたら、責務のズレが見えた

plans/ という名前なら多少混ざっていても気にならなかった情報が、definition/ と呼ぶと急に不自然に見えてきます。

たとえば、

今どの作業を優先しているか
次に何をするか
一時的に何がblockしているか

は、project definitionではありません。

一方、

requirements
design
testing
現在採用されているsystem state

はdefinition側です。

この整理を進めたのが、

54f5631
docs: move current state ownership into definition indexes

です。

jobs/ 側も、単なる旧 workbench/ の改名先ではなくなっていきました。

d8f401e
docs: govern jobs index and change units

さらに、

33be412
docs: use plus marker for active jobs

で、activeなJobも名前から識別できるようにしました。

jobs/
  +current-work/
  _later-work.md

ここまで来ると、

definition/
  このプロジェクトはどうあるべきか

jobs/
  今、何の仕事をしているのか

という役割分担がかなり明確になります。

ディレクトリ名は、思ったより意味を持っていた

最初は、

workbenchって名前、ちょっと違う気がする

くらいの話でした。

でも workbench → jobs にすると、今度は plans との関係がおかしく見え、plans → definition も必要になりました。

さらに名前を変えたことで、

これは本当にdefinitionなのか
これはJob側にあるべきではないか

という責務のズレまで見えやすくなりました。

AIエージェントが読むリポジトリでは、ディレクトリ名も単なる整理用ラベルではありません。

それ自体が、

ここに何があるはずか

をAIへ伝えるコンテキストになります。

だから、名前と実態がずれてきたら、名前だけでなく責務そのものを見直す必要がありました。

このあと jobs/ は、active/inactiveだけでなく、parent/childやhandoff、lifecycleまで持つようになっていきます。

そこは次の記事で書こうと思います。

plans/workbenchをdefinition/jobsに変えることになった話

workbench/ が実態に合わなくなった

jobs/ にしたら、今度は plans/ が変に見えた

まずは名前だけ変えた

名前を変えたら、責務のズレが見えた

ディレクトリ名は、思ったより意味を持っていた

関連リンク

`workbench/` が実態に合わなくなった

`jobs/` にしたら、今度は `plans/` が変に見えた