開発用ドキュメントの管理に関するポリシーを述べる。
整合性の方針
- 仕様・設計・コード間の整合性を維持するよう努めること。
- ただし全ドキュメントの整合性を100%保証しようとする仕組みは構築しない。コスト・期間・精度などの面から現実的でないためである。次善策としてAIと人間のレビューによって不整合を減らすことをベストエフォートで行う。
- チェックリストや自動テスト等を通し、用途に応じた品質を担保すること。決済などクリティカルな機能は速度より齟齬や抜け漏れがないことのほうが重要である。
- 整合性維持コストが高い仕様・設計は必要最小限に抑えること。
- 仕様に重要でない詳細を含めない。コードのサマリーが必要であれば生成する（例: terraform-docs）。
- ドキュメントはDRYに保ち、同一情報の重複管理を避ける。すなわち他のドキュメントに既に書かれていることを再度書かない。同じ内容を別の言葉で繰り返さない。
- 整合性を維持しないでよいドキュメントを明示する
- 例） コード生成のための作業指示書
- 仕様とコードのどちらが正しいかについて、機械的な優先順位を定めない。正しいコードを間違った仕様に合わせて変更してはならない。
- 注） 生成AIの暴走の防止が主な趣旨である