リポジトリ新設の閾値は「実装が始まるか」— 検証・計画段階の資産はドキュメント集約リポジトリに置く
開発環境
設計判断
ナレッジ管理
判断
新しい取り組みを始めるとき、成果物がまだドキュメントだけの段階で独立リポジトリを新設すると管理単位が重くなる。リポジトリ新設は「実装が始まる」タイミングに合わせ、それ以前の検証・計画資産は既存のドキュメント集約リポジトリ(個人・チームの private なメモ置き場)にサブディレクトリとして置く。
判断基準
- コードが生まれるかで決める。検証段階の企画・調査・計画は定義上まだプロダクトが存在しないので、プロダクト単位であるリポジトリを与えるのは順序が逆になる
- 判定が「進む」に変わり実装に着手する時点で初めてコードのリポジトリを作る。それまでの検証記録は集約側に残したままでよい(実装リポジトリに移す必要はない)
- 集約リポジトリに既に後続工程の成果物(実装計画など)が置かれているなら、前段の資産も同じ場所に置くと工程の連続性が保たれる
分散させたときのコスト
ドキュメント数ファイルのために独立リポジトリを持つと、次が分散する:
- git 履歴(小さなリポジトリが増え、横断で振り返れない)
- AI エージェントのセッション文脈とリポジトリスコープ設定(起動場所によって片方の資産しか揃わない)
- ナレッジ基盤・課題管理などのプロジェクト登録単位
可逆性(迷ったら集約に倒す理由)
集約 → 独立への切り出しはファイル移動で済むが、独立 → 集約は履歴の統合が要るため面倒。非対称なので、判断がつかない段階では集約側に置くのが安全側。
スクリプトを置くときの境界の引き方
ドキュメントリポジトリの境界を「スクリプト禁止」として引かない。その文書を生成・維持するためのスクリプトは文書の一部であり、対象内と見なしてよい。境界は守りたい不変式の側で引く:
- 守るのは「日常の操作が文書の編集と git だけで済む」こと。したがって禁じるのはスクリプトそのものではなく、ビルド・依存管理の持ち込み
- 具体化例: 単一ファイル・依存なし(言語ランタイム標準機能のみ、パッケージマニフェストを置かない)
- 制約とその理由をリポジトリの規約ファイル(エージェント向け指示ファイル等)に明記する
「例外」として書くと、例外は拡張されるか拒否されるかのどちらかに振れやすい。不変式と理由を書けば、次に触るとき(人でも AI でも)に「この変更は不変式を破るか」で判定でき、なし崩しの性格変化を防げる。