このページの目次

このページの目次

中核となるエンジニアリング原則

目的

本ガイドラインは、AI 支援によるアイデアの迅速な検証と POC 開発におけるエンジニアリング標準を定める。

目標は、プロジェクトを次の状態に保ちながら、速く進めることである。

  • シンプルである
  • 一貫している
  • 再現できる
  • 理解しやすい
  • 人間にも AI エージェントにも保守しやすい
  • アーキテクチャが意図せず崩れにくい
  • リポジトリ間で揃っている

中心原則は次のとおりである。

プロジェクト固有の判断を必要としないものは、すべて標準化する。

パッケージマネージャー、フォーマッター、リンター、タスクランナー、コミット規約、プリコミットフックといったエンジニアリング基盤を、プロジェクトごとに何度も選び直してはならない。

プロダクトの判断やアーキテクチャはプロジェクトごとに変わってよいが、エンジニアリングのツールチェーンは統一する。

検証速度の最適化

こうしたプロジェクトは、何よりもまずアイデアを速く検証するためのものである。

次のものは、本当に必要になってから導入する。

  • 抽象化
  • レイヤー
  • フレームワーク
  • サービス
  • インフラ
  • ドキュメント
  • プロセス
  • 汎用の拡張性

現在の問題を正しく解決する、最もシンプルな実装を選ぶ。

速く開発することは、雑に作ることではない。将来の混乱を招く近道や、AI 支援開発を不安定にする判断は避ける。

不要な選択を減らす

すでに標準化された事柄を、何度も判断し直してはならない。

本ガイドラインがツールを指定している場合、ユーザーが明示的に例外を認めない限り、そのツールは必須である。

次の理由だけでは、標準化されたツールを置き換えない。

  • 他のツールのほうが人気がある
  • フレームワークが別のツールを推奨している
  • 生成されたテンプレートが別のツールを使っている
  • AI エージェントが別のツールに慣れている
  • インターネット上の他のプロジェクトが別のものを使っている

真に技術的な非互換があるときは、標準ツールチェーンを変更する前にユーザーへ説明する。

ツールを黙って差し替えてはならない。

実績のある主流の選択肢を優先する

AI エージェントは、最新のドキュメントではなく学習データに基づいてコードを生成する。

出たばかりのバージョンやニッチな技術スタックは学習データに少ないため、幻覚によるクラッシュ、誤った API 呼び出し、挙動の不一致が起きやすい。

そのため、主流で実績のある選択肢をデフォルトとする。

  • ランタイムは LTS または成熟した系列を使う。デフォルトは Node.js Active LTS、機械学習では Python 3.12 とする。
  • ライブラリは、出たばかりのものやマイナーな代替案ではなく、主流でドキュメントが充実したものを選ぶ。
  • 出たばかりのメジャーバージョン、ニッチなフレームワーク、ニッチなランタイム(Bun ベースの技術スタックなど)を使うには、ユーザーの明示的な承認と理由の記録が必要である。
  • デフォルトの選定では、わずかな性能差よりも互換性と安定性を優先する。

モデルがその技術をどれだけ知っているかも、ベンチマークや機能一覧と並ぶ選定基準とする。

対症療法ではなく根本原因を扱う

警告、リントエラー、テスト失敗、型エラーなど、検証で問題が発生した場合は、次の手順で対処する。

  1. そのルールやチェックが何を守っているのかを理解する。
  2. 実際の根本原因を特定する。
  3. 合理的な範囲で、根本の問題を修正する。
  4. 影響を理解してから、設定変更を検討する。

次のことをしてはならない。

  • 警告が消えるまでコードをむやみに書き換える
  • CI を緑にするためにだけルールを無効化する
  • 問題を理解しないまま ignore コメントを追加する
  • テストを通すためにテストの要求水準を下げる
  • 解決せずに失敗を隠す

ルールがプロジェクトに本当に適さない場合に限り、設定を変更してよい。ただし、その変更は意図的かつ技術的に正当なものでなければならない。

最終原則

本ガイドラインは、人間と AI エージェントが同じツールやワークフローを毎回選び直さずに作業を進められる、予測可能な開発環境を整えるためのものである。プロセス自体を増やすことは目的としない。

選択がプロダクトに依存しない場合は:

標準化する。

バージョンや技術スタックの成熟度に差がある場合は:

実績のあるものを選ぶ。

変更がアーキテクチャに影響する場合は:

明示する。

検証チェックが失敗した場合は:

原因を理解する。

言語が異なる場合は:

境界を明示する。

AI エージェントがプロジェクトで作業する場合は:

不要な意思決定の余地を減らし、正しいアクションをデフォルトにする。