[テンプレート保守] 送り状の取り込み(フィードバックループ)
各プロジェクトで得た「汎用化できる学び」を ai-template へ還流させる取り込み手順。
前提(競合回避モデル)
- 各プロジェクトは自リポジトリの送り状
doc/output/to-template.mdに汎用学びを記録するだけ。ai-template を直接編集しない - 取り込みは ai-template 側で直列処理する(判断を1か所に集約=複数プロジェクト並行でも競合しない)
- 送り状の「状態」欄が二重取り込み防止の台帳として機能する
実行条件
- カレントが ai-template リポジトリであること(プロジェクト側では実行しない)
手順
1. 走査
- sibling プロジェクトの送り状を収集する:
ls ../*/doc/output/to-template.md - 自リポジトリのインボックスも収集する:
ls doc/input/from-projects/*.md(README.mdは除く) - インボックスが
README.mdだけなら、このPCではまだ構築されていない。/template-inboxを先に実行する(投函箱の実体はGit追跡外=PCローカルのため) - ai-template 自身の
doc/output/to-template.md(配布用の空雛形)は対象外 - 同じ学びが両方にある場合はインボックス側を正とする(
解決済みファイルのパスを持つため)
2. スコープ確認(Human in the Loop)
- 状態が
未取込の項目を一覧化し、種別・反映先候補とともに提示する - どの項目を取り込むかは人間が決める(GO をもらってから着手)
3. 出典の確認と汎用化の検証
- 各項目の出典ファイルを読み、送り状の「汎用化した形」が出典と整合するか確認する
解決済みファイルの記載がある項目は、動いている実物を読んでから写す(記述だけを頼りに書き直すと、検証済みの内容が劣化する)- プロジェクト固有の表現(固有の色・画材・フォント名等)をテンプレートに持ち込まない
4. 反映
- 「反映先候補」はあくまで候補。最終の置き場所は取り込み側が判断する(迷ったら
judgment-harnessの昇格判断を参照) - 複数の送り状が同じ箇所を触る場合は統合し、矛盾する場合は選択肢+トレードオフで人間に確認する
- rules は常時読み込まれるため薄く・最小で反映する(詳細は skill へ)
- 書くのは判断軸・優先順位・困ったとき何を疑うか・固有の手順/思想のみ。AIが既に持つ一般知識や、特定プロジェクトの具体例は書かない
- スキル記述も最小主義で: 含めるのは「最小の必須ステップ+判断軸」のみ。ドメイン固有の検証内容・網羅的な手順書・将来使うかもしれない詳細は、求められるまで書かない(構造仕様を先に、肉付けは発酵ループで)。反映後に「このスキル、半分に削れないか?」を自問する。厚いスキルは低コストモデルの誤読・過剰実行を誘発しやすい
5. 記録とコミット
- 取り込みの経緯・判断(候補から変えた場合はその理由)を
meta/adr-lite.mdに ADR-lite で記録する - 変更をコミットし、短縮ハッシュを控える
6. 台帳更新(二重取り込み防止)
- 取り込んだ項目の送り状の状態を
取込済(YYYY-MM-DD / 短縮hash)に更新する - インボックスとプロジェクト側の正本、両方の状態を倒す(片方だけだと次回に二重取り込みされる)
- プロジェクト側リポジトリでは送り状以外のファイルを触らない(コミットはプロジェクト側のセッションに委ねる)
送り状フォーマット(固定)
- 各項目: 種別 / 汎用化した形 / 反映先候補 / 出典 / 状態
- 雛形:
doc/output/to-template.md(apply_template で各プロジェクトに配布される)
よくある落とし穴
- 固有表現の混入(テンプレートが特定プロジェクトの色に染まる)
- 取込済マークの付け忘れ → 次回二重取り込みされる
- 反映先候補を鵜呑みにして rules が肥大化する(薄く・最小で反映する)