この記事の紹介
ai-engineering-agent——ソフトウェア エンジニアリング プロセス全体 (要件 → PRD → プロトタイプ → 契約 → フロントエンドおよびバックエンド実装 → テスト ケース → 変更ログ → 一貫性検証) を文書資産に凝縮した一連のプラクティス。
核となる命題は 1 つだけです。コンテキストは会話の中に存在するべきではなく、ドキュメントの中に存在する必要があります。
1. 原因: モデルはコードを作成できますが、プロセスは依然として人間の監視に依存しています。
過去 1 年間で、モデルのコードを作成する能力は急速に向上しましたが、エンジニアリング側の問題点はほとんど変わっていません。本当に際立っているのは次の 3 つの点です。
1. コンテキストはセッション後は存続しません。 要件の境界、フィールドの基準、命名規則、そして「この場所は変更できない」という暗黙の知識はすべて、会話の記憶に依存しています。新しいセッションを開き、すべてをゼロにリセットし、もう一度すべてを説明します。
2. 商品の追跡ができません。 要求の結論はチャット記録にあり、インターフェイスの定義は別の会話にあり、「なぜこのバージョンがこのように設計されているのか」を確実に言うことは誰にもできません。 3か月後に誰かが尋ねたら、彼らにできることは歴史を見ることだけです。
3. プロセスの規律は意識に依存します。 何を明確にすべきかを明確にしないままコードを書き始めました。契約が凍結される前に、私はフロントエンドとバックエンドを別々に書きました。フィールドを変更した後、10 個の微妙な矛盾がありました。
これらの問題の解決策は通常、「より適切なプロンプトワードを書く」ことによると考えられます。でも、口先だけの言葉では解決できないセッション、役割、ステージ全体での一貫性——それは工学的な問題であり、工学的な手段が必要です。
2. 設計原則: コンテキストは会話ではなく、ファイルです
アセット全体は、次の 5 つの原則に基づいて構築されています。
| 原則として | 着陸方法 |
|---|---|
| 唯一の真実の情報源 | 各概念は 1 か所でのみ定義され、ドキュメントの残りの部分でのみ参照されます。テクノロジースタックキャリバーのみが書き込まれています dev-contract.mdc 1 つの場所、コマンドとスキルがすべてそこを指します |
| 製品の引き渡し | ステージは対話に依存しませんが、上流のファイルの読み取りと下流のファイルの書き込みに依存します。このコマンドには、「何を読むか、何を書くか、そして誰が唯一の書き手であるか」が明確に示されています。 |
| ブレークポイントから実行を再開する | 各製品カタログには、 _meta/status.md（done / in_progress / blocked)、中断後に再実行して完了したステージをスキップします |
| 推測しないでください | 入力がない場合、または口径が不明な場合 blocked あるいは質問をやめて「合理的な仮定」を禁止する |
| 証拠の等級付け | 結論のポイント [已确认](ソースコードを直接読む)/ [推断]（根拠がある場合は根拠を記載）/ 【待验证】(検証提案が添付されているため、静的に読み取ることはできません) |
3 層または 4 層の構造: コマンド、役割、スキル、規則
なぜ4階建てなのでしょうか？なぜなら、「1 つのことを行う」ということは、実際には 4 つの異なる質問からなるからです。
| 層 | 回答された質問 | キャリア |
|---|---|---|
| 注文 | いつ、どのような順序で行うか | スラッシュコマンド(/ai-require-design、/ai-dev-backend…） |
| 役割 | 誰がそれを行うのか、境界はどこにあるのでしょうか? | サブエージェント (要件アナリスト、PRD 作成者、バックエンド開発者など) |
| スキル | 具体的にどうすればいいのか | 方法論 + プロンプトワード + テンプレート + スクリプト |
| 法令 | してはいけないこと | レッドライン条項 (非感作、読み取り専用、追加専用、コントラクトファースト) |
切断の利点は非常に直接的です。
- テクノロジースタックを変更したいですか?画像ファイルを 1 つだけ追加しますコマンド、ロール、プロトコルの行を変更する必要はありません。
- 制約を追加したいのですが、ルールを変えるだけすべてのコマンドは自動的に継承されます。
- リンクを追加したいのですが、コマンドを 1 つ追加するだけです既存のキャラクターとスキルを再利用します。
4. 2 本のメインライン
0-1 新建：需求分析 → PRD → HTML 原型 → 契约 → 前后端实现 → 测试用例 → 变更日志 → 一致性核验
1+ 存量：源码逆向 → PRD → HTML 原型 → 变更日志（双来源）→ 一致性核验
2 つの線の違いは、方向が反対であるというだけではありません。
- 0-1 需要から始まり、出力は「設計意図」の記録です。
- 1+ コードと git 履歴を振り返ると、出力は「実装事実」の記録です。各結論には「ファイル パス + 行番号」の証拠を添付する必要があります押し出すことができないものにはマークを付ける必要があります
【待确认】それを乗り越えるために「こうあるべき」を使用しないでください。変更ログには、Git 送信履歴 + 要件決定記録という 2 つのソースも必要であり、どちらも相互に裏付けられます。
5. 本当に機能する 5 つのメカニズム
1.契約ファースト+三本棒引き渡し
フロントエンドとバックエンドの並行開発の最大の落とし穴は、インターフェイスの口径が異なることです。 「3 本の棒」を使用した解決策は次のとおりです。
# 第 0 棒：只生成契约，不写业务代码
/ai-dev-backend --out=docs/dev --contract-only
# → contract/{api.yaml, api.md, data-model.md, enums.md, error-codes.md}
# 状态 draft → frozen，version v1.0
# 第 1、2 棒并行：前端与测试各自吃契约
/ai-dev-frontend --out=docs/dev
/ai-test-design --out=docs/dev
3つの注文互いに独立した同じものを共有する --out=docs/dev製品ごとにのみ揃えられます。フロントエンドは、コントラクト (パス、メソッド、フィールド名、タイプ、エラー コード) を逐語的に調整する必要があります。紛失物が見つかった場合独自の補足フィールドを作成しないでください代わりにアプリケーションを次のように書き込みます contract/_requests.mdバックエンドによって決定されます。
2. 作成者を個別にリストする: 「誰が変更したか」の問題を解決する
トレーサビリティ・マトリックスは段階間の調整の中核ですが、全員が書き込むとすぐにゴミ捨て場になってしまいます。したがって、各列書き込み権限を持つコマンドは 1 つだけです：
| リスト | ライター |
|---|---|
| 需要の源泉 | /ai-require-design / /ai-reverse-project |
| API | /ai-dev-backend |
| ページP | /ai-dev-frontend |
| バックエンドの実装 | /ai-dev-backend |
| フロントエンドの実装 | /ai-dev-frontend |
| ユースケースTC | /ai-test-design |
同様に、contract/ 唯一のライターはバックエンド コマンドです。これは権限に関するものではなく、「誰が責任を負うか」を常に決定できるようにするものです。
3. ブレークポイントから実行を再開します。ステータスはメモリではなくファイルに書き込まれます。
各製品カタログには、 _meta/status.md。中断後に同じコマンドを再実行します (セッションの終了、ネットワークの切断、要求の変更): ステータス ファイルの読み取り、スキップ done ステージから、 in_progress 続く;blocked 「不足しているもの」など、不足しているものを明確に印刷します。 prd/F08 受け入れ基準では契約を凍結することはできません。」
このコマンドは、範囲の絞り込みと再実行もサポートしています (--scope=F08) と強制やり直し (--fresh）。
4. テクノロジ スタックの 5 レベルのヒット シーケンス: ハードコーディングもデフォルト値による誘拐もありません
テクノロジー スタック分析は順番に評価され、以下にのみヒットします。
1. --stack=<画像 id> 显式指定，最高优先
2. /_meta/tech-stack.md 项目侧画像（缺失则回退读 0-1 落档的 <项目>/_meta/tech-stack.md）
3. 目标项目特征探测 读 pom.xml / package.json，匹配画像库的「识别特征」
4. .codebuddy/tech-stack.md 系统默认，仅在无任何工程结构可探测时使用
5. 均未命中 停下询问，禁止猜测
システムのデフォルトは 4 番目ですこのポイントはピットイン後に決定されました（次のセクションを参照）。
5. 監査可能な証拠の 3 つのチャネル
- 逆の結論: 「ファイル パス + 行番号」、信頼レベル 3 が含まれている必要があります。
- 変更ログ: 追加のみ。履歴は上書きまたは削除されず、修正は新しいエントリの追加のみ可能です。
- 契約変更：
version増分+_requests.md「誰が提案したか、どのインターフェースが影響を受けたか、そしてどのように裁定されたか」を記録します。
3 つを重ね合わせると、「なぜこれなのか」がファイル チェーンに沿って見つかるという効果があります。
6. 1 つの完全な動き
架空の lab-booking(大学の実験器具予約システムは 3 年間のストック プロジェクトを引き継ぎます) 例:
# 1) 存量逆向：出 PRD、原型、字段字典、变更日志、核验报告
/ai-reverse-project D:\work\lab-booking --out=docs/reverse-engineered --scope=reservation,instrument
# → 产出 modules/、prd/、prototype/、dictionary/、changelog/、review/
# 2) 冻结契约（只生成契约，不写业务代码）
/ai-dev-backend --out=docs/dev --contract-only --stack=backend-java-springboot
# 3) 前端与测试并行
/ai-dev-frontend --out=docs/dev --stack=frontend-vue2
/ai-test-design --out=docs/dev
# 4) 增量加一个功能（走契约变更流程）
/ai-dev-backend --out=docs/dev --scope=F08
ステップ 4 については特に言及する価値があります: 新機能 F08 まだ契約に反映されていないため、注文は直接書かれませんが、最初に contract/version から v1.0 にプッシュする v1.1状態が進む frozen → changed → frozen次に、トレーサビリティ マトリックスの「インターフェイス API」列と「バックエンド実装」列を実装し、最後に埋め戻します。
7. 踏んだ罠 (最も注目すべきセクション)
この一連のものは設計されたものではなく、衝突によって作成されました。いくつかの実際の修正:
落とし穴 1: 契約は下流側によって「都合よく変更」された。 フロントエンドはフィールドが欠落していることを発見し、フィールドを直接変更しました。 api.yaml 書き続けてください。 2 日後、誰がこのフィールドを追加したか、互換性があるべきかどうかは誰もわかりませんでした。 → 単一ライター + 変更リクエスト: 下流側のみに行くことができます contract/_requests.md 申請書を作成し、バックエンドの決定後に契約が締結されます。
ピット 2: テクノロジー スタックのデフォルト値が既存のプロジェクトを誘拐します。 デフォルトのスタックは Java 17 + Spring Boot 3.2 です。 Java 8 + Spring Boot 2.7 プロジェクトを引き継ぐ場合、デフォルト値が先にヒットするとスケルトン、依存関係、API の記述がずれてしまいます。 → システムのデフォルトをヒット順の 4 番目の位置に下げます。「エンジニアリング構造が検出できない」場合にのみ結論を示します。既存のすべてのプロジェクトが検出結果の対象となります。
落とし穴 3: 0-1 ステージでドロップされたイメージは、開発ステージでは読み取れません。 要件の段階では、テクノロジー スタックを次のように書き込みます。 <项目>/_meta/tech-stack.md実装段階が進む
ピット 4: 同じコンセプトに 4 セットのキャリバーがあります。 4 つのファイルのテクノロジ スタック分析は、「レベル 4」、「レベル 5」、「レベル 0」、「プロジェクト レベルがシステムのデフォルトより優先される」です。読者にはどちらを信じるべきかわかりません。 → 1 つの権威ある定義に収束する（dev-contract.mdc §七 第 28 条)、他のファイルは同じテーブルのみを参照および展開し、次のように変更します。ヒット順に書く(1→2→3→4→5)、読み間違えやすい優先番号ではなく。
落とし穴 5: 自分を律し、自分に勝つ。 ルール changelog/ これは「読み取り専用であり、3 つのコマンドのいずれも変更できません」としてリストされています。もう 1 つは、契約が変更されたときにバックエンドに変更ログを書き込む必要があります。 → 1つ追加例外のみをクリアする: 追加専用モードでの追加を許可します。 decision 記事を削除または変更してはなりません。
落とし穴 6: 用語の過剰な圧縮。 「技術スタックのヒットレベル＋判定基準」を「ヒット順とソース」に換算すると、その結果を見た者は唖然とするだろう。 → わかりやすい文章に戻します。ヒットシーケンス（ヒットのレベル）、ヒットソース（--stack パラメータ値/画像ファイルパス/検出根拠ファイル)。
落とし穴 7: ドキュメントの参照は腐ってしまいます。 章番号、ファイル パス、およびスクリプト パラメータがドキュメントに書き込まれた後、参照ファイルは変更されると失われます。ファイルを削除してもエラーは発生しません——それはただ、どこかの参照がひっそりと期限切れになっただけです。 → 定期的に機械的なチェックを行う: 文字化け、章番号参照の解析可能性、references/ そして templates/ 参照の存在、順序付きリスト番号の連続性、プロダクト パスの一貫性、同じ名前と異なる同義語。
落とし穴 1、2、4 は設計上の欠陥、落とし穴 3 と 5 は一貫性の欠陥、落とし穴 6 と 7 はコミュニケーションの問題です。 3 つのカテゴリはすべて、「次回から注意を払う」のではなくメカニズムを必要とします。
8. 該当・非該当
適切な：
- 複数の人が協力し、引き継ぎが必要なプロジェクト。
- 成果物をレビュー、追跡、レビューする必要があるシナリオ。
- 既存のコードを引き継ぐには、まず「現在のコードがどのようになっているか」を明確に説明する必要があります。
- 要件は繰り返し変更されるため、それぞれの変更が記録され追跡可能であることが望まれます。
以下には適していません:
- ワンタイムスクリプト、一時的なデータ処理。
- 1 人による短時間で迅速なプロトタイプの検証 – プロセスのオーバーヘッドがメリットを上回ります。
- 当面のニーズに応じて、モデルに「この関数の作成を手伝ってくれる」ようにしたいだけです。
判断基準はシンプルです。この事件から3か月が経ち、「そもそもなぜこんなことをしたのか」と聞きたい人はいるだろうか。 もしそうなら、そのプロセスを経る価値はあります。
9. 3 つのステップから始めます
1. 把 .codebuddy/ 拷到项目根目录（或独立工作目录）
2. 用 CodeBuddy 打开该项目，新建会话（规则只在会话开始时加载）
3. 按场景执行 /ai-reverse-project（存量）或 /ai-require-design（新建）
テクノロジースタックが異なる場合でもパッケージを変更する必要はありません。パッケージを書きます。
10. 結論
この一連のアセットは、本質的には「即発単語のコレクション」ではありません。ソフトウェアエンジニアリングプロセスの規律を文書として外部化する：
- プロセスは人間の記憶ではなく、順序に従って書かれます。
- 合意は対話ではなく議定書に書かれます。
- 製品には事実が書かれており、すべての結論には出典があります。
モデルの機能が向上すると、モデルの実行速度が向上しますが、これらのスケルトンが解決するのは次のとおりです。セッション、役割、ステージ全体での一貫性——それは別次元の問題ですね。
ステータスの説明：
ai-engineering-agentまだまだ磨き中ですが、まだ発見されていない問題がある可能性があります——仕様間の一貫性のない口径、無効なコマンド/スキルの参照、一貫性のない製品パスと仕様、曖昧な表現など。
ご使用前によくお読みいただくことをお勧めしますrules/使用したいコマンドを入力します。問題を見つけた場合や改善のアイデアがある場合は、ぜひ追加してください。フィードバックを送信する際に添付してください。ファイルパス + 行番号 + 現象最も効果的です。
