Tencent、Vibe Coding から AI 原生チームへ移行する実践的エンジニアリング手法を公開

AI を使って個人で趣味のプロジェクトを作るのは簡単ですが、実際の業務に適用すると話は別です。

著者：masoncai

この記事では、AI 原生（ネイティブ）な研发团队を構築する過程で得た経験をまとめました。主な内容は以下の 4 つです。

1. 汎用的な能力の構築方法
2. Harness（ハルネス）のエンジニアリング実践
3. 開発チームと製品チームの連携
4. 失敗から学んだ教訓

私たちは職種の壁を打破し、コードを書けない製品担当者も AI の力を借りて、独自に内部運用ツールを定義・実装できるようにしたいと考えています。これにより、チーム全体の開発効率を一段階引き上げたいのです。

全体像

AI を 24 時間連続で稼働させることは、Harness Engineering が到達できる能力の上限を示す一例です。しかし、この手法はゼロから始める場合や、既存業務との関連性が低いタスクに適しています。トークンコストが高くなるうえ、日常の開発現場ではあまり使われません。

実際の開発現場では、既存プロジェクトへの機能追加やバグ修正が主流です。そのため、重厚な自動化工程を組む必要はなく、軽量な「Vibe Coding（バイブコーディング）」で十分対応できます。

したがって、この記事では AI コーディングの能力上限をどう高めるかではなく、より日常的な課題に焦点を当てます。「AI による開発における品質の下限を守りつつ、トークン効率をどう向上させるか」です。

業界では「Prompt Engineering」「Harness」「Agent Loop」といった概念が次々と登場し、それぞれに活躍の場があります。私自身が行っている多くの作業も、本質的にはこれらの「ハルネス（安全装置・枠組み）」を整備する行為そのものです。

しかし、チーム内の全員が最初からこうした概念を理解して適用する必要はありません。コードこそが、ビジネスロジックを最も正確かつ効率的に記述する言語です。多くの人にとって、まずは AI を高品質に使いこなしてコーディングタスクを完了させるスキルを身につけることが、最も現実的な第一歩となります。

ROI が最も高く、即効性があるのは、まず AI コーディングを稼働させ、その上で実際のニーズに応じてセキュリティや管理の「柵（ガードレール）」を着実に築いていくことです。

今回紹介するプロジェクト名は「Vibe Flowing」です。これは業務属性が極めて強い「AI 原生（ネイティブ）な海外ネットワーク運用プラットフォーム」であり、主に海外ネットワーク運用に関するビジネスシーンに特化しています。

私たちが定義する「AI 原生開発」とは、ページ機能や定時タスク、エージェント型 AI、オープン API、外部システムとの連携など、プロジェクトを構成するあらゆるコンポーネントと機能を AI が一元管理することを指します。

利用者は単に要件を記述すればよいのです。簡単な要望なら対話形式ですぐに完了しますが、複雑な案件はまずドキュメントとして整備し、開発プロセスで合意形成を図った後に実装に入ります。

この仕組みにより、チーム内ではコードが書けるかどうかに関わらず、誰もが参画できます。ネットワーク運用の担当者が開発者でなくても、要件定義からコーディング、そして検証までの一連の流れを完遂できるのです。

まさにこれこそが、AI がチームに与える恩恵を最も直感的に示す例です。参入障壁が十分に低くなれば、人間の関与範囲は自然と広がっていくものです。

課題はどこにあるのか

私たちがなぜこのアプローチを採用したのか、その理由を語る前に、まず現状の課題について整理しましょう。

Vibe Coding（AI によるコーディング）の参入障壁はすでに非常に低くなっています。ネットワーク運用担当者が AI コーディングプラットフォームを活用すれば、自分だけでウェブページを作成し、データを確認したりグラフを描いたりして、その場しのぎのニーズを満たすことが可能です。しかし、使い続けるうちに問題が顕在化してきました。

1. 輪の再発明、データの非連携、独自解釈の横行

各担当者が作成したウェブサイトは、それぞれが異なるバックエンドシステムの API を呼び出しています。運用系、ネットワーク管理系、CMDB（構成管理データベース）、SNMP など、分野ごとにバラバラに開発が進み、互いの状況が把握できていません。

例えば、専用線の情報を検索する際にも、担当者が違うだけで同じデータを二度手間かけて取得することになります。さらに、認証方式やデータの定義基準さえも統一されておらず、混乱を招いています。厄介なのはデータが各システムに孤立しており、相互に関連付けて分析できない点です。もし専用線の流量に異常が発生した場合、流量の推移、パケットロス率、通信キャリアの品質などを同時に確認するために、複数のページを行き来する必要があり、かつデータ同士が一致しないという事態も頻発します。

こうしたページを一つのポータルに集約し、リンク一覧でアクセスしやすくしようとする試みもありました。しかし、実態は「草の根レベル」の対応に過ぎません。リンクが増え続ける一方で、ページデザインは統一されておらず、「どの情報が最新か」「現在も有効か」「問題発生時に誰に連絡すべきか」を明確に示すことができません。時間が経つとこれらは「レガシー化」し、誰も手をつけられず、かつ手をつけたがらない状態に陥ってしまいます。

1. 本格的なシステム構築への障壁

運用担当者が、実際に使い続けられるシステムを作ろうとする際、最初の大きな壁となるのが各システムの API アクセス権限の取得です。ネットワーク管理システム、CMDB、データベースなど、それぞれにアクセス許可やアカウント発行が必要で、手続きや承認待ちが付き物です。

ようやく権限を取得できたとしても、API ドキュメントの不備、フィールドの意味不明確さ、認証方式のバラつきといった問題が残ります。AI に連携を任せても、こうした状況では失敗しやすいものです。AI に原因調査を依頼しても、試行錯誤の結果としてトークン（計算リソース）を大量に消費するだけで、肝心の核心にたどり着けないケースが多々あります。

これらは業務ロジックそのものよりもはるかに複雑な基盤レベルの問題であり、文脈がない状態では AI が効率的に問題を特定するのは困難です。

結論として、Vibe Coding は「その場限り」のツール作成には適していますが、「継続的に進化し続けるシステム」を構築するには不十分です。必要なのは AI の能力不足ではなく、プロの開発者が事前に用意した土台です。ログ管理、認証、権限制御、外部 API のラッパー化、データベース変更プロセス、定時タスクなど、基盤となる部分はまず整備しておく必要があります。

この土台が整っていれば、AI はその上で開発を進める際に毎回ゼロから始める必要がなく、インフラの問題に時間やトークンを浪費することもありません。

これが「Vibe Flowing」を構築した出发点です。まずは企業レベルの堅牢な基盤を整え、その上で AI が継続的に開発を進められるようにすることで、チーム全体の能力範囲を広げていくのです。

専門の開発者が作業を効率化するだけでなく、非エンジニアのメンバーも本格的な業務システムの構築に参加できるようになります。

効果の概観

具体的な手法を解説する前に、実際に稼働している 2 つの事例を見て、「AI 原生的な開発」がどのような体験をもたらすか実感してみましょう。

シナリオ 1：AI 原生による開発全体のフロー

運営担当者が「出口トラフィックを AS（Autonomous System）単位で集約したサンキー図を追加したい」と要望した場合、従来のように仕様書を作成したり開発チームにスケジュール調整を依頼したりする必要はありません。自分自身ですべて完結できます。

まず、「anydev」の開発コンテナをテンプレートから起動します。手動での設定は一切不要です。CodeBuddy を開き、AI に「トラフィック分析ページに、出口トラフィックを AS 単位で集約したサンキー図を追加したい。Top 20 の AS におけるトラフィック分布が見られるようにしてほしい」と伝えるだけで OK です。

AI はまず、どのような次元（ディメンション）を表示するか、データの出所はどこか、ページのどこに配置するかといった要件をすり合わせます。簡単な会話で要件が確定します。

その後、開発が始まります。バックエンドの API、フロントエンドのコンポーネント、データベースへのクエリなど、フルスタックの開発を一気に実行します。開発中も AI が自ら開発環境を起動し、テストを実行し、ログを確認してデバッグを行います。人間の介入は不要です。

開発が完了すると、AI は運営担当者にアクセス URL を通知します。担当者はブラウザで実際に動作を確認できます。

確認結果に満足すれば「OK」と返信するだけです。AI が自動的に静的解析とセーフティネットテストを実行し、コードをリモートブランチへプッシュして MR（Merge Request）を作成します。その後、管理者の承認を経てメイン環境へマージされます（現在は AI による自動承認の導入を進めています）。マージ完了前でも、運営担当者は自分自身の開発コンテナ上でその機能をすぐに使用可能です。

この一連のプロセスで、運営担当者が一行もコードを書いたり、Git を操作したり、「ブランチ」という概念を理解する必要さえありません。

下の画像は「Vibe Flowing」プロジェクトのコミット履歴です。基盤が整えば、チーム全員が AI を活用して自らの要望を実現できるようになります。

この AI 原生の開発体系は、すでに海外のネットワーク運用チームやコントローラー運用チームで実用化されています。統一された AI 開発インフラを基盤に、環境構築から完全自動化までわずか 3 分で完了し、誰でも開発に参加できる体制が整っています。

シナリオ 2：AI ネイティブなエージェント開発プロセス

ある運用担当者が「専用線の品質分析を行う AI エージェント」を作りたいと考えたとします。従来の Agent プラットフォームの構成方法に従うなら、他の開発チームが MCP（Model Context Protocol）やスキルを公開するのを待つ必要があります。その後、自分自身でプロンプトを書き、ツールを設定し、検証を実行しなければなりません。このプロセスは非常に時間がかかります。

しかし、新しいシステムでは、運用担当者は AI に以下のように指示するだけで済みます。

「専用線 ID を入力すると、自動的に流量の傾向、パケットロス率、遅延データを取得し、品質評価の結論と異常の原因を提示するエージェントを作りたい。验收基準は、任意の 1 本の専用線を選んでも、30 秒以内に構造化された分析レポートを出力できることだ」

この目標を受け取った AI は、自らコードリポジトリ内を探検します。

• 既存のデータモデルを確認し
• 再利用可能なサービスを見つけ出し
• そのまま使えるツール関数を選別する

そして、AI 自身がシステムプロンプトを作成してエージェントの行動規範と出力形式を定義し、ツール関数をパッケージ化してデータクエリ機能を統合します。最後に、これを Agent フレームワークに登録します。

次にデバッグフェーズです。AI は自らエンドツーエンドの検証を実行し、実際に 1 本の専用線を選んで出力結果を確認します。验收基準を満たさない場合は、プロンプトを調整したり、モデルを変更したり、ツールからの返却形式を変えたりして反復的に改善を行います。

このように、エージェントの開発プロセス全体で AI が自分自身と対話し、自ら検証を行うため、人間の監視は不要です。

開発が完了すると、AI は運用担当者に実際に使えるエージェントを渡します。運用担当者は Web 上の Agent チャットページにアクセスし、「専用線品質分析用エージェント」を選択するだけで、すぐに利用を開始できます。

具体的な例を示します。

1. 自然言語による要件定義

1. AI によるコーディングと自主的なテスト・反復

1. エージェントの対話結果

まとめ

これらの 2 つのシナリオに共通するのは、「人間は『何を』定義し、AI が『どうやって』実現するかを担う」という点です。これが私たちが考える「AI ネイティブな開発」の本質です。単なる個人の生産性向上ツールではなく、チーム全体の新しい働き方そのものです。

では、具体的にどのような実践があるのか見ていきましょう。

玩具から企業級システムへ

1. 内部業務 SDK の連携

当社のネットワークプラットフォームには、多数の内部運用システムが存在します。これまでに Python 製の業務 SDK を開発し、網管システムや CMDB（構成管理データベース）、SNMP、七彩石、ログ解析など、多様なサードパーティ製サービスのインターフェースをカプセル化しました。

Vibe Coding で生成されたプロジェクトでは、まずこの SDK の統合が最優先事項となります。現行の運用を支える SDK は従来 Python 3.6.8 に固定されていましたが、昨年は Python 3.12 への移行実験を行いました。基礎的な依存関係を更新したため、新規プロジェクトではそのまま導入可能です。ただし、既存プロジェクトの場合は、事前に依存関係の互換性問題を解決しておく必要があります。

この SDK はプライベートパッケージであるため、CI パイプラインでプライベートリポジトリの認証設定が必要です。また、AI エージェントに SDK の機能を理解させるために、コードリポジトリへサブモジュールとして追加します。実際のコーディングでは、エージェント自身に探索させればよく、各インターフェースを説明するドキュメントを追加する必要はありません。

ログ出力や設定情報の取得といった基本的な機能については、IDE の Rules に数行の指示文を記述するだけで十分です。例えば、「ログは from nBroker.lib.logger import log を使用せよ」といったルールを設定すれば、AI はこれを記憶し、以降のコード生成で常に正しく利用します。

2. 汎用的な基盤機能

企業級運用システムには、以下の汎用的な機能が備わっている必要があります。

• ログ機能
• ページレベルの権限制御
• アクセス監査ログ
• 公開 API
• MCP ツール（Model Context Protocol）
• 定期タスク
• ワークフロー管理

これらの機能をプロジェクトごとにゼロから構築するのはコストが高すぎます。そのため、私たちはこれらを標準的なインフラとして確立し、新規プロジェクトではこれを継承して利用しています。以下に、それぞれの具体的な実装方法について解説します。

ログ管理

プロジェクト全体で SDK に用意された統一ログメソッドを直接再利用し、呼び出しシグネチャを一貫させることで、独自のロギング機構を再構築する必要はありません。AI がコード生成を行う際も、Rules ファイルに「このルールに従う」と一行記述するだけで十分です。毎回個別に指示を出す必要はありません。

ページレベルの権限制御

RBAC（ロールベースアクセスコントロール）モデルを実装しました。ユーザーの身份情報は太湖網から注入され、バックエンドでデコードされた後、login_name が取得されます。さらに人事システムを参照して所属する部門とチームを確認します。権限ルールはデータベースに保存されており、「ページ単位」と「操作単位」の 2 つの粒度で制御可能です。管理者リストは七彩石というリモート設定ツール経由で管理できるため、動的な調整が容易です。

この仕組みは AI には透明であり、AI が新しいページを作成する際も「リソースに制限があるか」を宣言するだけで、権限検証は自動的に適用されます。

ページアクセス監査

すべてのリクエストは認証ミドルウェアを経由します。ユーザーの身份、アクセスパス、API Token の使用履歴などはすべてデータベースに記録され、後から監査や追跡が可能になります。

公開 API

外部システムとの連携には API Token メカニズムを採用しています。Bearer Token とカスタムヘッダーの 2 つの方法をサポートします。各トークンには、アクセス可能なパスのホワイトリスト、管理者リスト、有効期限を設定できます。トークンの平文は管理者のみが閲覧可能で、一般ユーザーにはマスクされた表示となります。この仕組みにより外部システムの接続を安全かつ可控に保ちつつ、AI 自身も Token の作成と管理を自律的に行えます。

MCP ツール

FastMCP をベースに MCP Server を構築し、専用線分析やトポロジー分析といったコア機能を MCP ツールとしてパッケージ化しました。これにより他の AI クライアントから呼び出しが可能になります。MCP のパスは認証ホワイトリストに含まれており、外部システムとの統合がスムーズです。

定期タスク

APScheduler を活用して、デコレータ登録方式を実現しました。新しい定期タスクを追加する際は、@cron_job デコレータ関数を書くだけで十分です。タスク ID、実行間隔、説明を記述するだけで完了します。定期タスクは独立したプロセスで動作するため、API の処理をブロックしません。

フロントエンドからはタスクの一時停止・再開・間隔変更・手動トリガーが可能です。また、マルチコピー環境下ではデータベースによる競合制御（パイルアップ）により、1 つの指令が重複して実行されるのを防ぎます。AI が新しい定期タスクを追加する際も、業務ロジックの関数を書くだけでよく、スケジューリングや管理のための「足場」は自動的に準備されます。

ワークフロー

DBOS を活用して、シンプルなワークフロースケジューリング機能を実装しました。これによりプラットフォームは複雑なプロセスの実行を支えることができます。これらのプロセスには、人間の介入が必要な待機タスクや非同期コールバックの待ち時間を含めることが可能です。その結果、複雑なタスクが数ヶ月にわたって中断なく継続して実行されることが可能になります。万一中断しても、過去の状態から復元できるため、「耐久性のある関数（Durable Function）」として機能します。

小規模プラットフォームであってもこれらの機能が内蔵されていれば、AI がこれらをすべて処理できるようになり、システム間の複雑な連携を必要としません。これが AI 原生開発の基盤条件です。

Harness のエンジニアリング実践

1. マスターリポジトリ（大倉）の組織形態

私たちはモノレポ（単一リポジトリ）形式を採用しています。バックエンドの flo/ ディレクトリとフロントエンドの web/ ディレクトリは、同じ Git リポジトリ内に配置されています。

この形式の利点は、AI が 1 つのセッションで前後端のコードを同時に参照できることです。フルスタックの変更を行う際にも文脈が途切れることがなく、異なるリポジトリ間を行き来する必要がありません。

バックエンドのディレクトリ構造は、厳格な階層規約に従っています。呼び出し方向は「コントローラー（API 層）→ サービス（業務層）→ モデル（データ層）→ ソース（外部インターフェース）」と下流のみで、逆方向への依存や同層間の相互参照は禁止されています。

これに加え、「分析（analysis）」「定期タスク（cron）」「CLI ツール（cli）」「エージェント（agent）」などの独立したディレクトリも用意されています。これらの制約は AGENTS.md ファイルに明記されており、AI がコードを生成する際にも常に遵守されます。

各機能ディレクトリには _framework/ というサブディレクトリを設け、フレームワークレベルの「足場」コードを格納します。業務ロジックは業務関数の実装に集中し、スケジューリングやライフサイクル管理はフレームワーク側が担います。これにより、AI が新機能を実装する際もビジネスロジックに注力でき、インフラの詳細に邪魔されることはありません。

フロントエンドでも同様で、components/ は業務ドメインごとにディレクトリを分け、各コンポーネントには対応する Storybook の story ファイルを用意します。views/ ではコンポーネントの調整のみを行い、コードを整理保ちます。この構造は直感的で、AI がコードベースを検索する際も素早く特定でき、人間によるレビューもしやすくなります。

以下にフロントエンドのコンポーネント化例を示します。多くの再利用可能なコンポーネントが蓄積されており、これらは主に業務モジュールごとに分類されています：

2. Rules と Skills で AI に「ルール」と「スキル」をインストールする

大規模なディレクトリ構造は「コードをどう整理するか」を決めますが、Rules と Skills は「AI がどのように作業するか」を定義します。このステップが極めて重要です。制約を加えなければ AI は毎回「自由奔放」に動き、品質は運任せになります。一方、適切な制約を設ければ、作業の質には下限が保証されます。

Rules：シナリオ別に読み込まれるプロジェクトのガードレール

私たちは複数の階層を持つ Rules を設計し、シナリオに応じて自動的に AI のコンテキストに読み込むようにしています。

第一層はプロジェクトルートにある AGENTS.md です。これは CodeBuddy IDE や With 開発環境向けの汎用ルールファイルで、すべての開発ガードレールとエンジニアリングの嗜好を網羅しています。具体的には、ファイル作成の禁止事項、バックエンドの階層化規範、フロントエンドの工程規約、データベース変更の手順、トラフィックチャートの配色方針、ネットワークトポロジーの可視化における好みのスタイルなどが含まれます。AI は毎回のセッションでこのファイルを参照するため、実質的に「プロジェクト仕様書」を常に持ち歩いているようなものです。

第二層は .vscode/anydev_rule.md です。これは統一された開発コンテナ向けのルールファイルで、各開発者のコンテナ環境に自動的に読み込まれます。AGENTS.md がエンジニアリング規範に重点を置くのに対し、anydev_rule はより開発プロセスの制約とユーザー保護に焦点を当てています。その核心となるのは以下の鉄則です。

• 3 段階フローは必須：どんな小さな変更（テキストの修正など）であっても、「要件検討 → 実装 → 確認・コミット」の 3 段階を必ず踏まなければなりません。各段階の間にはユーザーによる明確な承認が必要で、AI が勝手に「小改动なら議論をスキップしてもよい」と判断することは禁止されています。
• ユーザーは非専門開発者：技術用語が登場する場合は、まず平易な言葉で説明し、実行前に方針を提示します。ユーザーに選択肢を選ばせるのではなく、迷った場合は必ず停止して確認を求めます。
• ブランチ管理は AI が代行：ユーザーがブランチを意識する必要はありません。AI が一貫して管理し、自動的に dev-$ 用户名 ブランチへ切り替え、リモートの dev ブランチと同期し、競合も処理します。
• Git 操作のガードレール：破壊的なコマンドの使用を禁止し、変更範囲は最小限に抑えます。ファイル削除の前には必ず確認を取得します。

製品担当者が陥りやすい誤解を事前に指摘する仕組みも重要です。例えばユーザーが「データを削除して」と指示した場合、AI は即座に「anydev アカウントには DELETE 権限がありません」と通知し、代わりにソフトデリート（論理削除）の利用を提案します。

第三の層は、社内版プラグイン「CodeBuddy」の記憶システムです。プロジェクトルールの中には「Memory（記憶）」として保存される項目があり、「データベースの時間フィールドは DATETIME を統一する」「フロントエンドコードを変更後は必ず type-check を実行する」「流量グラフでは入力が緑色、出力が青色」といった具体的な指針が含まれます。これらの記憶は AI が関連するタスクを実行する際に自動的に読み込まれ、毎回手動で説明する必要はありません。

このように 3 つのルール層を積み重ねることで、「AI はこのプロジェクトで何ができ、何ができず、どう行うべきか」という制約事項をほぼ網羅できます。設計の基本原則はただ一つ。「ルールは一元管理し、シーンごとに読み込み、重複させない」ことです。AI のコンテキストウィンドウ（文脈の容量）には限りがあります。ルールが散在していたり重複したりすれば、トークン消費が増えるだけでなく、AI が混乱を招く原因にもなります。

重要なルールとして、Anydev クラウド開発のガードレールと実際の開発例を示します。左側のファイルディレクトリには 4 つの主要な開発制約が表示されており、右側は AI が開発を完了し人間による検証に回す際のレスポンス例です：

Skills：AI に「専門スキルパッケージ」を事前インストールする

Rules が「ルールや規範」を管理するのに対し、Skills は「能力」を担います。私たちは開発プロジェクトで頻出するシーンに対応した一連の Skill を蓄積しています。

• Agent 作成：ReAct Agent の完全なワークフローを実装します。コード探索、プロンプト作成、ツール定義、登録、検証までを一貫して行います。
• ワークフロー作成：DBOS を基盤としたワークフローオーケストレーションにより、永続化やリトライが必要な複雑なタスクを処理します。
• Changelog 公開：changelog の項目を生成し、git tag を作成してバージョンリリースを完了させます。
• フロントエンドデザイン：「AI 特有の安っぽい雰囲気」を排除し、高品質な UI を構築するスキルです。
• Vue 開発：Vue3、Composition API、TypeScript に基づく開発規範とベストプラクティスを実装します。
• 工蜂（コードプラットフォーム）操作：リポジトリ管理、マージリクエスト、コードレビュー、Issue 管理などを行います。
• コードの腐化対策：これは特に重要です。AI 原生の開発が加速すると、コードベースの進化速度も劇的に上がりますが、その分「コードの腐化」も急速に進みます。そこで私たちは、責任を分離した 2 つのスキルを作成しました。1 つはコードの問題をスキャンして Issue を作成する役割、もう 1 つはその Issue を引き受け問題を修正する役割です。「審判と選手が同一人物」という状況を避け、Agent にこれらのスキルを定期的かつ小規模に実行させることで、リポジトリ全体のコード品質を保証します。
• iWiki：社内文書の検索と編集機能を提供します。
• スキル作成：新しい Skill の作成や既存スキルの最適化を行います。

これらの Skill は CodeBuddy 内版プラグインで自動的に読み込まれます。AI が対応するシーンに遭遇すると、人間が手動で呼び出すことなく自動的にトリガーされます。例えばユーザーが「専用線の品質分析を行う Agent を追加して」と指示した場合、「Agent 作成」のスキルが即座に起動し、定義されたワークフローに従って実行されます。具体的にはまず既存コードを探索してデータモデルを理解し、次にプロンプトとツールを作成、最後に登録と検証を行います。

Rules と Skills の関係は、前者が「ミスを防ぐ守り」、後者が「作業を速める攻め」です。Rules だけあれば AI は正確に動きますが、毎回手順を探る必要があり非効率です。一方、Skills だけあれば動作は速いものの、規範から外れるリスクがあります。両者を組み合わせれば、AI はルールを守りつつ効率的に動き、人間の介入コストを最小限に抑えることができます。

1. TDD（テスト駆動開発）の実践と取舍

AI を活用したコーディングにおいて、TDD（テスト駆動開発）には微妙な課題があります。AI はテストコードを素早く作成できますが、その内容が「自欺欺人」になりがちです。具体的には、Happy Path（順調なケース）のみをカバーしたり、アサーション（検証条件）が甘すぎたりする問題です。

そのため、私たちは厳格な「先にテストを書く」というプロセスに固執するのではなく、ルールによる制約で品質を保証するアプローチを採用しています。

バックエンドでは pytest を、フロントエンドでは vitest を用いたコンポーネントテストと、Playwright による E2E テストを実施します。コードを提出する前には必ず静的解析チェックが必須です。バックエンドでは ruff（コードスタイル）と ty check（型チェック）、フロントエンドでは oxlint と vue-tsc を実行します。これらのコマンドは AGENTS.md に記載されており、AI が自ら実行するように設計されています。

「フロントエンドの機能テストでバックエンドまでカバーできるか」という問いに対して、私たちの経験則は以下の通りです。E2E テストは「フロントエンド → API → データベース」という全体の流れを検証できるため、ビジネスロジックの正しさを保証する上で価値があります。しかし、バックエンドのユニットテストには「問題箇所の特定」に特化した役割があります。E2E テストが失敗した際、それがフロントエンドのレンダリング不具合なのか、バックエンドのロジックエラーなのかを切り分けることができないからです。

したがって、私たちの取舍は以下の通りです。コアとなるビジネスロジックには必ずバックエンドのユニットテストを実装し、フロントエンドの E2E テストは主要なユーザーフローに焦点を当てます。両者は代替関係ではなく、補完関係にあります。

カバレッジ目標は 70% を目安としていますが、これは数値そのものを達成することが目的ではなく、開発を阻害する閾値ではありません。重要なのは、変更されたファイルに対してテストがカバーされているかどうかです。数字の追求よりも、実務的な改善を重視しています。

実際の運用では、「テスト」よりも「受入（アセスメント）」を重視しています。ネットワーク運営チームからの要求に対し、最終的な受入基準は「ページの挙動が期待通りであること」とします。この受入プロセス自体が、エンドツーエンドの検証として機能しています。AI が機能を開発した後、Playwright のヘッドレスモードでスクリーンショットを取得し、要件を提出した担当者が確認するフローを確立することで、開発から受入までの闭环を形成しています。

1. 軽量 SDD（Spec Driven Development）

SDD（仕様駆動開発）は重厚なプロセスのように聞こえますが、多くのチームでは各種のオープンソース Spec フレームワークを用いて全体を管理しようとしています。しかし、私たちはあえて複雑なフレームワークを導入せず、シンプルなファイル命名規則だけで同等の効果を実現しています。

核となる考え方は、「要求仕様書こそが開発における唯一の入力である」という点です。簡単な要件は対話で完結させ、複雑なものは Markdown 形式のドキュメントとして記述します。AI はこのドキュメントを読み込み、議論を経て開発と受入へと進みます。

ドキュメントのフロールールは以下の通りです。

features/ ディレクトリに要求仕様書を配置し、「draft_」→「ready_」→「done/」という 3 つのフェーズを順次通過させます。

前缀：未确定的方案，AI 和人一起讨论迭代

ready_：方案对齐确认，可以开始开发

开发完成后移到 done/ 目录

方案讨论文档放在 ai_docs/running/ 目录，同样遵循 draft_ → ready_ 的命名约定，完成后移到 ai_docs/done/。

这套机制的好处是：AI 一次会话中读完一个 ready_ 文档就拥有了完整的需求上下文，不需要人来反复解释。而文档本身也是 AI 协助写的，运营同事口述需求，AI 整理成结构化文档，开发同事 review 确认后，AI 改前缀为 ready_，并开始开发。

一句话：文档命名约定就是工作流。不用额外的项目管理工具，文件名本身就在表达状态。

5、封装 CLI 工具

AI 在开发过程中经常需要做一些“运营性”操作：执行 DDL、回填数据、管理配置。如果让 AI 自己写临时脚本去 import db 跑，既不安全也不留痕。我们给 AI 封装了几个 CLI 工具，让这些操作有规可循。

flow-db-exec：数据库变更执行工具，是 DB 变更的唯一入口。支持单条 SQL 执行和按文件行号片段执行两种方式，还有 dry-run（干跑）模式。这个工具做了三件事：一是高危关键字（DROP/DELETE/TRUNCATE）硬拦截，和数据库账号权限互为双保险；二是强制留痕，SQL 必须先写到 changelog.sql 再执行；三是执行结果清晰可读，SELECT 结果格式化输出，写操作返回受影响行数。

flow-config：业务配置管理工具，支持增删改查和按前缀过滤，配置存在数据库里，方便运行时动态调整。多说一句：很多团队习惯把所有配置丢到远程配置中心去管，但实际用下来会发现，评审发布流程比较繁琐，配置和代码分属两个系统，割裂感强，AI 也很难直接操作。其实大部分业务配置，例如阈值、开关、参数等，没那么敏感，没必要搞那么重。我们直接用项目内部的数据库表管，配一个 CLI 加一个管理页面就够了。配置和代码同在一个仓库，AI 能直接读写，改完即生效，不用跨系统走流程。Key 按模块分层命名（如 threshold.surge_ratio），同模块配置聚合成 dict 读取，代码里统一走 app_config 模型，不直接拼 SQL。这套机制轻量、透明、AI 友好，运营同事也能在页面上自助改。

run-cron：定时任务独立进程入口，只启动调度器不启动 API，避免重任务阻塞线上接口。

这些 CLI 工具的设计理念是把高频运营操作封装成“安全、留痕、可重复”的命令，AI 用着高效，人审查也放心。AI 不用理解底层连接、事务这些细节，调一个命令就行。

6、前端组件化

フロントエンドのコンポーネント化はもはや常識ですが、AI によるコーディングという文脈では、特に重要な意味を持ちます。それは、コードレビューを可能にするからです。

もし Vue ファイルが 1000 行にも及ぶ場合、AI が一箇所を変更した際、その影響範囲を人間が即座に把握するのは困難です。しかし、100〜200 行の小さなコンポーネントに分割し、それぞれの役割を明確にしておけば、AI の変更は通常 1 つや 2 つのファイルに集中します。レビュー時には、これらの特定のファイルだけを確認すれば済みます。

私たちが定めたルールは以下の通りです。

• Vue SFC（Single File Component）は 500 行以内とし、超えた場合は分割する
• 独立した機能ドメインはサブコンポーネントとして切り出し、再利用可能なロジックは composable へ移す。ユーティリティ関数は utils/ ディレクトリに配置する
• サブコンポーネントは 100〜200 行、composable は 30〜70 行を目安とする
• すべてのコンポーネントには Storybook の story を用意する

最後の項目が特に重要です。現在のプロジェクトではすでに 143 個の story ファイルが存在し、ほぼすべてのコンポーネントをカバーしています。Story はデザイナー向けの資料というだけでなく、AI と開発者に対する「コンポーネント仕様書」です。story には各コンポーネントの状態や props の組み合わせが定義されており、AI が新機能を開発する際、まず story を参照することで既存のコンポーネント能力を確認できます。これにより、不要な再実装（輪子の再作成）を防ぎます。また、新しいコンポーネントを実装した後に story を追加することは、一種の自己テストを行うことにもなります。

ページビュー層では「スマートコンポーネント＋プレゼンテーションコンポーネント」のパターンを採用しています。View 層は調整役として機能し、専用 ID や出口 ID、時間範囲などを子コンポーネントに渡すだけです。各データカードは自らデータを取得（fetch）し、自らレンダリングを行います。View 層をクリーンに保つことで、新しいカードを追加してもメインファイルが肥大化するのを防いでいます。

これらの制約事項は AGENTS.md に明記されており、AI がフロントエンドコードを生成する際に自動的に遵守されます。稀にルール違反が発生した場合は、指摘するだけですぐに修正・分割できます。

1. AI に「問題」を見せる

AI によるコーディングにおける最大のリスクは、処理が遅いことではなく、「間違えていることに気づかない」ことです。AI に「問題」を見せることが、品質保証の鍵となります。

私たちのアプローチは以下の 4 つの層で構成されています。

第一層：静的解析による即時フィードバック。バックエンドでは ruff と ty check を、フロントエンドでは oxlint と vue-tsc を使用しています。これらのツールの出力結果は AI が直接読み取ることができます。AI はコードを記述した直後に自らチェックを実行し、エラーが発生すれば自分で修正します。これは人間によるレビュー待ちよりもはるかに効率的です。

第二層：AGENTS.md によるルールの集約。プロジェクトのルートディレクトリにある AGENTS.md には、開発上のガードレールやエンジニアリングの嗜好がすべてまとめられています。具体的には、ファイルの制限、階層化の規範、コードスタイル、データベース変更のプロセスなどが含まれます。AI は毎回のセッションでこのファイルを参照するため、常にアクセス可能な「プロジェクト仕様書」を持っているようなものです。ルールを集中管理することで、AI の遵守率が高まります。

第三層：開發服務由 AI 自主管理。項目通過一個 dev.sh 腳本統一啟動前後端開發環境，這個腳本本身也是由 AI 編寫的。後續如何修改、日誌查看位置以及進程監控等細節，全部交由 AI 處理。開發者無需記憶這些技術細節，只需對 AI 發出「啟動開發環境」或「查看後端日誌」的指令即可。AI 對開發環境的掌控力越強，其自主發現和解決問題的能力也就越出色。

第四層：Playwright 驗證。AI 完成功能開發後，會利用 Playwright headless 模式進行截圖、檢查 API 請求並驗證交互行為。這相當於讓 AI 自行完成了一遍 QA 測試。

這四層機制疊加後，大部分問題都能在 AI 的對話過程中被發現並修復，等到人類審查時，代碼已經相對成熟。

8、數據庫變更管控

數據庫變更在生產系統中是最敏感的操作。為此，我們設計了一套「極簡、透明、可驗證」的管控流程。

極簡：所有 DDL/DML 操作均通過 flow-db-exec 單一入口執行，AI 無需編寫臨時腳本。對於常見的加字段、加索引或按主鍵更新等操作，直接執行並告知結果即可。

透明：任何變更必須先記錄在 changelog.sql 中（註明日期與目的），同步更新主結構定義文件，然後再按行號執行剛追加的片段。這樣既能追溯變更歷史，也能確保新環境重建數據庫時擁有完整的記錄。

可驗證：根據風險等級採取不同的處理方式。

此外，時間字段統一使用 DATETIME 類型，禁止使用 BIGINT 時間戳，以方便運營人員理解。AI 在數據庫操作上擁有清晰的邊界感，既保證了效率，又確保了安全。

9、Agent 工作流

Agent（智能體）是該項目的核心能力之一。這裡想重點分享的並非 Agent 框架的技術細節，而是 AI 原生的 Agent 研發方式。

傳統做法是：開發者手動搭建 Agent 平台，在管理後台配置提示詞、註冊工具並設置參數，最後將能力對外暴露。在這種模式下，每新增一個 Agent 都需要人工在多系統間反覆操作，導致維護成本高企且迭代緩慢。

少し面白い話ですが、以前私は「設定型」を売りにしたエージェントプラットフォームの立ち上げを主導しました。ドラッグ＆ドロップでフォームを埋めるだけで Agent を構築でき、Knot よりも早くリリースされたのです。

しかし現在、AI のコード生成能力が劇的に向上したことで、あえて重い仕組みを作る必要はなくなりました。むしろ、Agent をコードで記述する方が自然です。プロンプトはファイルとして、ツールは関数として、登録はデコレータとして扱う。「Everything as Code」こそが、AI 原生の研開発プロセスなのです。

私たちのアプローチは全く異なります。AI に「業務目標」を与えれば、既存のコードベースを基にエンドツーエンドで Agent を作成させるのです。

具体的には、「専用回線の品質分析」といった新しい Agent が必要になった際、AI に「どのような業務課題を解決し、どんな能力を持つべきか」を伝えるだけで十分です。残りの作業はすべて AI が行います。

• コードベースを検索し、既存のデータモデルやサービスインターフェース、ツール機能を理解する
• システムプロンプトを作成し、Agent の行動規範と出力フォーマットを定義する
• 必要なデータクエリや分析機能を Agent が呼び出せるツールとして、既存関数の再利用または新規作成を行う
• レジストリに登録し、統一されたセッション管理やストリーミング出力フレームワークに接続する
• Storybook の story を追加して検証を行う

外部システムへの手動設定も、管理画面でのフォーム入力も不要です。すべての成果物はコードベース内にあり、追跡可能でレビューでき、ロールバックも可能です。

ここで強調したいのは、より深い設計思想です。「システムにどのような能力があるか」は AI 自身が見つけます。プロジェクトの全要素——データモデル、サービスインターフェース、ツール関数、Agent プロンプト、フロントエンドコンポーネント、定期タスクなど——がすべて単一のコードベースに含まれており、AI はそれら全てにアクセスできます。これが「AI 原生」の設計です。能力を管理画面や外部システムに隠すのではなく、すべてコードとして公開し、AI が直接探索・理解・再利用できるようにするのです。

従来のエージェント組織形態は「プラットフォーム＋管理画面設定」でした。Agent プラットフォームが中心となり、ツールやプロンプトは管理画面で維持され、人間が手動で登録や設定を行います。このモデルでは AI は全体像を把握できず、新しい能力を追加するたびに人間が平台に手動で「教える」必要があります。

一方、私たちのアプローチは「コード＝設定」です。Agent のプロンプトはコードファイル、ツールはコード関数、登録はコードデコレータです。AI が必要な能力があれば、コードベース内で直接検索し、見つかったものをそのまま利用できます。中間工程は一切不要です。

この設計がもたらすメリットは明白です。AI が新しい Agent を追加する際、白紙から描き始めるのではなく、すでに豊富な機能を持つエコシステムの中で「レゴブロックを積み上げる」ような感覚で作業できます。既存のトラフィッククエリサービスがあればそれを再利用し、チャートレンダリング用のツールがあればそのまま接続し、他の Agent のプロンプト記法があれば参考にします。管理画面からゼロから設定するよりも、はるかに効率的です。

この仕組みを支えているのが、フレームワーク層での統一された抽象化です。ReactAgent ベースクラスがモデル設定、コンテキスト注入、ストリーミングイベント出力、セッション永続化などの共通機能を担います。新しい Agent を追加する際は、「名前」「システムプロンプト」「利用可能なツール」の 3 つだけを考えればよく、残りはベースクラスと登録メカニズムが自動的に処理してくれます。

さらにいくつかの設計上の工夫をご紹介します。

1. Agent は SSE（Server-Sent Events）でストリーミング出力し、接続断に耐えるように設計されています。クライアント側でページを再読み込みしても、直前の切断位置から再開可能です。数分かかる分析タスクを実行中に刷新しても、進捗は失われません。

1. ツールの蓄積には重要な規約があります。ツールからの返却値は、生 JSON ではなく Markdown 文字列として出力することです。これにより、Agent が内容を理解しやすくなり、トークン消費を大幅に削減できます。また、人間が画面で確認する際にも読みやすくなります。

以下の画像は Agent 作成機能の一部を示しています。完全な内容は、記事末尾のオリジナルコードリポジトリをご参照ください。

AI 原生型の Agent 開発における最大の価値は、人間が業務上の成果に集中できる点にあります。つまり、「どのような課題を解決し、何を導き出すか」という本質的な問いに注力するのです。

一方、プロンプトの記述方法やツールの連携、フレームワークの登録といった技術的な実装は、すべて AI がエンドツーエンドで処理します。人間のリソースは「正しい設定」を調整することに費やすのではなく、「正しい課題」を定義することに集中させるべきです。

1. Anydev による統一開発環境

前述した Rules（ルール）、Skills（スキル）、CLI ツールなどは、AI に作業を遂行させるための安全装置のようなものです。しかし、それらを実装する前に解決すべき前提があります。それは「開発環境そのものをどう用意するか」という問題です。

従来の開発モデルでは、新入社員がプロジェクトに参加する際、開発環境の構築だけで数時間を要することが珍しくありません。システム依存関係のインストール、Python や Node のツールチェーン導入、プライベートリポジトリの認証設定、環境変数の生成、フロントエンドとバックエンドの依存関係のセットアップ、そして開発サービスの起動など、一連の手順が必要です。各工程でつまずくリスクがあり、例えばシステムパッケージのバージョン不一致や、プライベートリポジトリのアドレスを忘れること、あるいは環境変数の設定漏れによるサービス起動エラーなどが発生します。非エンジニアにとって、この参入障壁はほぼ克服不可能なレベルです。

私たちは、自動化された初期化スクリプトによってこの課題を解決しました。社内の Anydev クラウド開発コンテナを活用することで、コンテナ起動時にすべての設定が自動的に完了します。コンテナの作成から利用可能になるまで 3 分以内で、その間も人間の手を介することなく完了します。

具体的な実装は scripts/system/setup.sh スクリプトで行われ、7 つのサブステップを順に実行します。

最初のステップは開発環境の登録です。コンテナ起動直後に、自身の IP アドレスやフロントエンド・バックエンドサービスのアドレス、開発ブランチなどの情報を、プロジェクトの DevOps 管理ページへ自動登録します。これにより、運用担当者は Web ページ上で誰が開発環境を稼働させているか、そのアドレスがどこにあるかを即座に確認できます。リンクをクリックするだけで機能検証が可能となり、「あなたの開発環境のアドレスはどれですか？」といった問い合わせが不要になります。

2 つ目のステップはシステム依存関係のインストールです。mysql-devel、gcc、gettext など、コンパイルや実行に必要なシステムパッケージを自動的にインストールします。コンテナ内の dnf コマンドで稀にネットワークの不安定さが発生するため、最大 3 回のリトライ処理を実装しています。

3 つ目のステップはツールチェーンの導入です。Python パッケージ管理用の uv と、フロントエンド用パッケージ管理の pnpm、そして社内開発ツールである rtk をインストールします。インストール直後に環境変数をソース（読み込み）し、その後の手順で現在のシェルがすぐに利用できるように設定します。

4 つ目のステップは開発規範の注入です。.vscode/anydev_rule.md ファイルを .codebuddy/rules/ ディレクトリへコピーします。これにより、AI がコンテナ内で起動した瞬間に自動的にプロジェクトの規範を読み込みます。