開発ログからチュートリアル本文を組み立てる

この mdBook は、最初から完成した原稿があったわけではありません。 実際には、開発を進めながら残した planning docs と active logs を材料にして、あとから本文へ再構成しています。

この章では、その変換のしかたを見ます。 なお、この章そのものも最初から人間が立てたものではなく、AI エージェント側から「開発ログをどう本文へ変換したかも章にしたほうがよい」と提案し、それを採用する形で差し込みました。 そういう意味でも、この章はこの project の作り方をよく表しています。

先に、どの repo が何を持つかを固定する

本文化の手順に入る前に、repo の役割分担を先に決めておく必要があります。 これを曖昧にしたまま進めると、開発メモと公開原稿が混ざってしまい、あとから整理するコストが急に上がります。

この project では、次のように分けています。

• current repo
  • planning docs、active logs、fact-report、運用設計の正本を持つ
  • 試行錯誤や未確定事項も含めて残す
• tutorial repo
  • current repo の記録をもとに、読者向けの章へ再構成した本文を持つ
  • 説明の流れを優先し、内部向けの細部は必要な分だけ取り込む

この前提があるので、「まず current repo に一次記録を残し、その後に tutorial repo へ説明として編み直す」という順番を取りやすくなります。 以降の節では、その変換のしかたを具体的に見ていきます。

まず、どの記録が何のためにあるかを分ける

この project では、agent-builder-kit を土台にしつつ、記録を一か所へ雑に積むのではなく、役割ごとに分けています。 そのおかげで、あとから本文を書くときに「何が事実で、何が判断で、何が読者向けの説明候補か」を切り分けやすくなります。

たとえば、この project では次のように使い分けています。

• project-intake, discovery-brief, plan-spec
  • 何を作るつもりだったか、最初に何を前提としていたかを見る
• blocks, chunks, tickets
  • どの粒度で仕事を分け、どこで再計画したかを見る
• fact-report
  • 実際に何をやったか、何が起きたかを見る
• decision-log
  • どの判断を採用したかを見る
• gotcha-log
  • どこで詰まり、どう回避したかを見る
• command-log
  • 手順として再利用できるコマンドを見る
• before-after
  • 変更前後を読者へ見せやすい粒度で拾う
• article-source-map
  • 章ごとに、どの記録を根拠に使うかを整理する

raw log は current repo に残し、tutorial には抽象化して渡す

ここでいう raw log とは、開発中にそのまま残している一次記録のことです。 この project では、たとえば次のようなものが raw log にあたります。

• ticket 本文の実施結果
• fact-report
• 実行コマンド
• block / chunk / ticket の進捗メモ
• 差し込み要求や、その時点での未解決事項

これらは current repo に残します。 理由は単純で、raw log は再利用価値が高い一方、そのまま public な本文へ流すと情報量が多すぎるからです。

tutorial repo 側へ渡すときは、次の順で 1 段抽象化します。

• どの記録が事実の根拠になるかを選ぶ
• その中から読者に必要な部分だけを抜き出す
• 設計判断や学びとして読める順に並べ替える

つまり raw log は「公開しない」のではなく、「そのまま貼らない」と考えると分かりやすいです。 current repo に十分な一次記録があるからこそ、tutorial repo 側では説明の密度を調整しながら再構成できます。

role ごとに、どの段で何を残すかを分ける

この変換を安定して回すには、「誰がいつ何を残すか」をあらかじめ分けておく必要があります。 この project では、おおむね次のように考えています。

• plan-manager
  • block の採否、順序変更、上流方針の確定を残す
  • 後で「なぜその方針になったか」を説明したいときは decision-log の材料になる
• task-planner
  • chunk / ticket の分解や依存の組み替えを残す
  • どの章でその再計画を扱うかは article-source-map に寄せていく
• task-worker
  • 実装や docs 更新の事実を ticket 本文と fact-report に残す
  • その中で、読者価値のある詰まりどころや手順だけを gotcha-log や command-log へ切り出す

つまり、まず各 role が本来の正本 docs を更新し、そのあとで記事化価値のある部分だけを補助 log に寄せます。 最初から全部を記事向けに書こうとしないことが大事です。

事実と解釈を混ぜない

本文を書くときにいちばん大事なのは、事実と解釈を最初から混ぜないことです。

たとえば fact-report に残っているのは、

• 実行したコマンド
• 変更したファイル
• 成功したこと
• 失敗したこと

といった一次記録です。

一方で、「なぜその判断をしたか」「読者に何を学んでほしいか」は、そのままでは本文になりません。 これは decision-log や article-source-map を使って、あとから意味づけしていきます。

つまり流れとしては、

• まず事実を残す
• 次に、その事実の中から使うものを選ぶ
• 最後に、読者向けの順番へ並べ替える

という順になります。

いきなり本文を書かず、source map を間に置く

この project では、本文を書く前に article-source-map.md を置いています。 これはかなり重要です。

source map があると、

• この章はどの記録を根拠にするか
• まだ何が足りないか
• 補助画像を使うなら何があるか

を、本文と切り離して考えられます。

この一段を挟むことで、「勢いでいい文章を書いたけれど、根拠がどこか分からない」という状態を避けやすくなります。

さらに言えば、source map は raw log と本文の間の「交通整理」でもあります。 fact-report、decision-log、gotcha-log、command-log、before-after を全部そのまま本文へ運ぶのではなく、 どの記録をどの節の根拠に使うかを、いったんここで落ち着いて決めます。

変換のタイミングは ticket 完了ではなく、章の節目で見る

raw log が増えてくると、毎回すぐに tutorial 側へ流したくなります。 ただ、この project ではそこも意図的に分けています。

• current repo では ticket 完了ごとに記録を残す
• tutorial repo では block close や milestone の節目で編成する

この差を設けることで、internal では細かい学びを落とさず残しつつ、public 側ではまとまった話として読める形に整えやすくなります。

もし ticket ごとにそのまま本文へ流してしまうと、読者にとっては途中経過が断片的に見えやすくなります。 そこで current repo 側に raw log を貯め、節目が来たときに source map や fact-report を見ながらまとめて編成する、という流れを取ります。

この project では、その節目を主に次のように見ています。

• current repo
  • ticket 完了ごとに事実と補助ログを追加する
• tutorial repo
  • block close、または milestone ごとに source map を見ながら章へ編成する

この 2 段構えにしておくと、開発の勢いを落とさずに記録を取りつつ、公開側では読みやすいまとまりを作れます。

記録はそのまま貼らず、読者向けに並べ替える

開発ログは時系列で積み上がりますが、チュートリアル本文は必ずしも時系列で読むのが最適とは限りません。

たとえば、この mdBook でも、

• 先に agent-builder-kit の導入を書く
• 次に plan-manager と task-planner の流れを書く
• そのあとで task-worker や記録の使い方を書く

という順にしています。

実際の作業順と完全に一致していなくても、読者が理解しやすい順に並べ替えてよい、ということです。 ただしそのときも、根拠は source map と fact-report に戻れるようにしておきます。

この方法は他の成果物にも転用できる

この章のポイントは、mdBook を書くためだけの手法ではないことです。 成果物が別のアプリやライブラリであっても、

• 開発中に一次記録を残す
• active logs で判断と詰まりどころを整理する
• source map で本文との対応を作る

という流れはそのまま再利用できます。

つまり agent-builder-kit の価値は、単に plan を管理することではなく、「開発の記録そのものを、あとから説明可能な教材へ変換しやすくすること」にもあります。 少し大げさに言えば、開発しながら、そのまま次のチュートリアルの下書きも育てている、という感覚に近いです。

注釈: decision-log, gotcha-log, command-log, before-after, article-source-map は、agent-builder-kit に最初から同梱されていた機能ではありません。 開発の途中で、「今やっている作業もあとで本文に使いたい」と task-planner に伝えたところ、新しい chunk が差し込まれ、そのための記録機構がこの project の中へ追加されました。