中核となるエンジニアリング原則
目的
本ガイドラインは、AI 支援によるアイデアの迅速な検証と POC 開発におけるエンジニアリング標準を定める。
目標は、プロジェクトを次の状態に保ちながら、速く進めることである。
- シンプルである
- 一貫している
- 再現できる
- 理解しやすい
- 人間にも AI エージェントにも保守しやすい
- アーキテクチャが意図せず崩れにくい
- リポジトリ間で揃っている
中心原則は次のとおりである。
プロジェクト固有の判断を必要としないものは、すべて標準化する。
パッケージマネージャー、フォーマッター、リンター、タスクランナー、コミット規約、プリコミットフックといったエンジニアリング基盤を、プロジェクトごとに何度も選び直してはならない。
プロダクトの判断やアーキテクチャはプロジェクトごとに変わってよいが、エンジニアリングのツールチェーンは統一する。
検証速度の最適化
こうしたプロジェクトは、何よりもまずアイデアを速く検証するためのものである。
次のものは、本当に必要になってから導入する。
- 抽象化
- レイヤー
- フレームワーク
- サービス
- インフラ
- ドキュメント
- プロセス
- 汎用の拡張性
現在の問題を正しく解決する、最もシンプルな実装を選ぶ。
速く開発することは、雑に作ることではない。将来の混乱を招く近道や、AI 支援開発を不安定にする判断は避ける。
不要な選択を減らす
すでに標準化された事柄を、何度も判断し直してはならない。
本ガイドラインがツールを指定している場合、ユーザーが明示的に例外を認めない限り、そのツールは必須である。
次の理由だけでは、標準化されたツールを置き換えない。
- 他のツールのほうが人気がある
- フレームワークが別のツールを推奨している
- 生成されたテンプレートが別のツールを使っている
- AI エージェントが別のツールに慣れている
- インターネット上の他のプロジェクトが別のものを使っている
真に技術的な非互換があるときは、標準ツールチェーンを変更する前にユーザーへ説明する。
ツールを黙って差し替えてはならない。
実績のある主流の選択肢を優先する
AI エージェントは、最新のドキュメントではなく学習データに基づいてコードを生成する。
出たばかりのバージョンやニッチな技術スタックは学習データに少ないため、幻覚によるクラッシュ、誤った API 呼び出し、挙動の不一致が起きやすい。
そのため、主流で実績のある選択肢をデフォルトとする。
- ランタイムは LTS または成熟した系列を使う。デフォルトは Node.js Active LTS、機械学習では Python 3.12 とする。
- ライブラリは、出たばかりのものやマイナーな代替案ではなく、主流でドキュメントが充実したものを選ぶ。
- 出たばかりのメジャーバージョン、ニッチなフレームワーク、ニッチなランタイム(Bun ベースの技術スタックなど)を使うには、ユーザーの明示的な承認と理由の記録が必要である。
- デフォルトの選定では、わずかな性能差よりも互換性と安定性を優先する。
モデルがその技術をどれだけ知っているかも、ベンチマークや機能一覧と並ぶ選定基準とする。
対症療法ではなく根本原因を扱う
警告、リントエラー、テスト失敗、型エラーなど、検証で問題が発生した場合は、次の手順で対処する。
- そのルールやチェックが何を守っているのかを理解する。
- 実際の根本原因を特定する。
- 合理的な範囲で、根本の問題を修正する。
- 影響を理解してから、設定変更を検討する。
次のことをしてはならない。
- 警告が消えるまでコードをむやみに書き換える
- CI を緑にするためにだけルールを無効化する
- 問題を理解しないまま ignore コメントを追加する
- テストを通すためにテストの要求水準を下げる
- 解決せずに失敗を隠す
ルールがプロジェクトに本当に適さない場合に限り、設定を変更してよい。ただし、その変更は意図的かつ技術的に正当なものでなければならない。
最終原則
本ガイドラインは、人間と AI エージェントが同じツールやワークフローを毎回選び直さずに作業を進められる、予測可能な開発環境を整えるためのものである。プロセス自体を増やすことは目的としない。
選択がプロダクトに依存しない場合は:
標準化する。
バージョンや技術スタックの成熟度に差がある場合は:
実績のあるものを選ぶ。
変更がアーキテクチャに影響する場合は:
明示する。
検証チェックが失敗した場合は:
原因を理解する。
言語が異なる場合は:
境界を明示する。
AI エージェントがプロジェクトで作業する場合は:
不要な意思決定の余地を減らし、正しいアクションをデフォルトにする。