腾讯エンジニアリング、チーム向け AI コーディング実装規範を公開

「好代码」の基準をシステムに組み込み、AI に制約された環境で自律的に作業させる

画像：https://wechat2rss.bestblogs.dev/img-proxy/?k=c33454e9&u=https%3A%2F%2Fmmbiz.qpic.cn%2Fsz_mmbiz_jpg%2FKVER9adz906CRXOoRfUM7JNPRo13DsrWXDUjQXDWVNrW4S93hBPNjN7qI2d9ogPyuT24A6eIl3h4jmJdIVRnaAwvPTEd13Q6E5IWomQJ6ibA%2F0%3Fwx_fmt%3Djpeg

画像：https://wechat2rss.bestblogs.dev/img-proxy/?k=1131f926&u=https%3A%2F%2Fmmbiz.qpic.cn%2Fsz_mmbiz_gif%2Fj3gficicyOvasVeMDmWoZ2zyN8iaSc6XWYj79H3xfgvsqK9TDxOBlcUa6W0EE5KBdxacd2Ql6QBmuhBJKIUS4PSZQ%2F640%3Fwx_fmt%3Dgif%26from%3Dappmsg

著者：atreusliu

コードを納品するコストはほぼ無料になりましたが、「良いコード」を納品するコストはまだ高いままです。Harness Engineering が目指しているのは、この「良いコード」の基準をシステムに組み込み、AI に制約された環境で自律的に作業させることです。

なぜチームの全員がこの規範に従う必要があるのでしょうか？

AI コーディングツールはソフトウェア開発のあり方を変えつつあります。チームの誰もが AI を使って素早くコードを生成できるようになった今、真に差をつけるのは「誰が速く書けるか」ではなく、「誰が良く、安定して、保守性の高いコードを書けるか」という点です。

この規範は束縛ではありません。それはチーム共通の言語であり、品質の最低ラインです：

個人にとっては、正しい AI 協働習慣を身につけさせ、失敗や手戻りを防ぎ、AI を真のパワーアップツールとして機能させるものです。

チームにとっては、全員が出力するコードのスタイルを統一し、アーキテクチャを整え、レビューと保守性を確保することで、協業の摩擦を減らすものです。

プロジェクトにとっては、品質基準をツールチェーンに固定化し、人員の変動によってプロジェクトが失控することを防ぐものです。

本ドキュメントの位置づけ：

第 1 部（第 1〜2 章）では「なぜ」「何」について答えます。Harness Engineering の核心理念と、AI コーディングを統合したアーキテクチャ設計を解説します。

第 2 部（第 3〜9 章）では「どうするか」について答えます。段階的な導入ロードマップ、具体的な設定手順、日常開発の標準作業手順（SOP）、反パターン（失敗事例）のまとめ、そして私たちが構築した harness-audit Skill を活用した自動コンプライアンス自己検査の方法を提示します。

第 3 部（第 10 章）で総括を行います。

読者の皆様への一点のお願い：

MCP、Skills、Rules、SDD、知識ベースといった概念については、社内・社外で「それらとは何か」を解説する入門記事がすでに多数存在します。本稿ではこれらの基本的な定義を繰り返すスペースはありません。本稿が本当に伝えたいのは、以下の 2 つの点です。

第一に、これらが Harness システムの中で果たす機能上の役割です。MCP や Skills を個別に見れば理解しやすいツールですが、Harness の 6 つの柱の中に組み込んだ際、それぞれがどのような役割を担い、どのレベルの問題を解決し、AI ワークフローのどの段階で効果を発揮するのか——これがチームがこれらのツールを効果的に使いこなすかどうかを決定づける鍵となります。

第二に、実際の開発現場においてこれらがどのように連携するかです。MCP はデータ伝送路を提供し、Skills はドメインの知見をパッケージ化し、知識ベースは業務コンテキストを注入し、Rules は行動の境界線を引きます——これらのツールが孤立して存在するわけではありません。真の威力を発揮するのは、これらを組み合わせて使うときです。本稿では、要件開発、バグ修正、コードレビューといった具体的なシナリオを通じて、これらがどのように協調して機能するかを明確に解説します。

実は日々の開発において、私たちはすでに Harness の考え方を部分的に活用しています。ただ、これらのツールの使い方や運用方法を体系的なフレームワークとして統一する仕組みが欠けていただけです。

各ツール背後にある設計思想を理解し、自分のプロジェクトでどのツールを使うべきか、どう組み合わせるべきか、あるいはいつ使うべきでないかを明確にするために、このガイドラインは用意されました。

第一部分：理念とアーキテクチャ

一、核心理念：Harness Engineering（驾驭工程）

#### 1.1 Harness Engineering とは何か？

2026 年 2 月、OpenAI は『Harness Engineering: Leveraging Codex in an Agent-First World』という論文を発表しました。このプロジェクトでは、当初 3 人だったエンジニアチームが後に 7 人に拡大し、手書きコードを完全に禁止した条件下で、AI エージェントを用いて 5 ヶ月間にわたり 100 万行以上のコードを作成し、1,500 件の Pull Request をマージしました。その結果、開発効率は約 10 倍に向上しています。

"Harness"という用語は馬術に由来しており、本来の意味は「馬具」です。具体的には、手綱や鞍、鐙などを指します。未驯服な馬は強力ですが、耕運や荷物の運搬、戦場での使用を任せることはできません。AI も同様です。

Agent = Model + Harness

モデルが知能を提供し、Harness がその知能を実際の生産力へと変換します。

LLM 自体には状態管理も、ツールへのアクセス権限も、記憶機能も備わっていません。Harness レイヤーこそが、モデルに「手足と記憶」を付与するエンジニアリングインフラストラクチャです。あなたが記述するすべてのコードや設定されるルールは、すべて Harness の一部となります。

┌─────────────────────────────────────────────────────┐

│ 应用层 (Application) │

│ IDE プラグイン / CLI / Web UI / ユーザーインタラクション │

├─────────────────────────────────────────────────────┤

│ Harness 层 (Agent Harness) │

│ ツール呼び出し・コンテキスト管理・権限検証・状態永続化 │

│ 実行オーケストレーション・評価検証・制約回復・記憶システム │

├─────────────────────────────────────────────────────┤

│ 模型层 (Model) │

│ LLM (Claude / GPT / DeepSeek など) │

│ 指示の理解・テキスト生成・意思決定 │

└─────────────────────────────────────────────────────┘

#### 1.2 なぜ Harness が必要なのか？—— Vibe Coding の三つの致命的な問題

Harness による制約がない「Vibe Coding（雰囲気コーディング）」は、スタートは極めて速い → 中盤で混乱する → 後期に崩壊するという道を進むことになります。

プロジェクト規模が大きくなると、AI エージェントの能力は低下し、バグを修正しようとしたら新たなバグが二つ生まれるという現象が頻発します。

可読性と保守性の喪失

開発プロセス全体がブラックボックス化し、コードがどのように生成されたかを知る者はエージェントのみで、人間は思考の過程に関与していません。人が引き継ぎたいと思った瞬間、数千行に及ぶ「ゴミのようなコード」を最初から読み直す必要があり、結局書き直したほうがマシだと感じる状況です。

こうした課題を解決するのが Harness Engineering です。その核心となる要素は以下の通りです。

安全境界：権限制御、監査ログ、追跡拒否機能

可観測性：トークン使用量の計測、コストの追跡、意思決定の記録

信頼性：リトライ機構、フェイルオーバー戦略、確定的なバックアップ

拡張性：ツールエコシステム、スキルシステム、複数エージェント間の調整

1.3 Harness の 6 つの柱とコーディングへの適用

Harness Engineering は、エージェントが動作する環境を 6 つの柱に分解し、それぞれの柱に対して開発規範で対応するツールや実践を用意しています。以下に詳しく解説します。

上記の画像は、公式 WeChat 記事（https://mp.weixin.qq.com/s/gs5ndvlMqM-Y4jg1_D2aFw）より引用したものです。同記事では Harness の詳細な解説がなされているため、本稿では実践に直結するツールの構成についてのみ焦点を当てます。

柱 1：コンテキスト管理（Context Architecture）

課題：AI のコンテキストウィンドウは容量に限界があり、コストも高いです。どうすれば AI が適切なタイミングで必要な情報を見られるようにできるでしょうか？

実践とツールの対応関係：

• 段階的な情報開示：AGENTS.md に約 100 行の目次を作成し、ARCHITECTURE.md や Rules など詳細なドキュメントへのリンクを設けます。一度に数千行の情報を読み込ませるのではなく、必要な部分だけを開示します。
• 構造化された仕様書：requirement.md や task.md といった Spec ファイルを用意し、要件や設計判断を Git リポジトリ上に記録します。これにより AI はいつでも参照できる「長期記憶」を得られます。
• 変更の隔離：changes/ ディレクトリを活用し、Proposals メカニズムによって「増分変更」と「既存コード」を分離します。これにより、既存ロジックへの誤った影響を最小限に抑えられます。
• 知識の階層化（Skills）：スキル情報を「説明→指示→詳細手順」の 3 レベルに分け、必要に応じて段階的に読み込みます。これによってコンテキストの使用量を節約できます。
• 外部知識ベースの接続：チームの Wiki、コードリポジトリ、カスタムファイルなどを知識ベースとしてマウントし、AI との対話時に自動または手動で参照できるようにします。これにより AI は業務文脈を把握できます。
• コードの知識化（AI Wiki）：コードベースから自動的に構造化された知識ドキュメントを生成します。これにより AI は個々のファイルを読み込むことなく、プロジェクト全体を理解できるようになります。

いくつかの原則があります。

• AI に数千行に及ぶ単一の規範ファイルを渡さないこと。
• 階層化されたインデックスを構築し、AI が必要に応じて詳細へ掘り下げられるようにすること。
• チームの Wiki や業務ドキュメントを知識ベースとしてマウントし、AI に業務文脈を持たせること。
• リポジトリ内の知識を「システム記録（System of Record）」として扱い、チャット履歴への依存を避けること。

OpenAI も同様の失敗を経験しています。初期段階では「巨大な AGENTS.md」を試しましたが失敗しました。正解は、複数の専門的なドキュメントに分割し、目次でつなぐことです。

柱 2：ツールシステム（Tool System）

課題：AI はどのようにしてコードリポジトリの外にある現実世界と接点を持ち、特定の分野における専門能力を獲得できるのでしょうか？

AI エージェントの能力を最大化するには、3 つの要素が連携するシステムが必要です。それは「MCP（外部世界との接続）」「Skills（専門家の経験の封装）」「知識ベース（業務コンテキストの注入）」です。

MCP（Model Context Protocol）—— 外部データソースへの接続

MCP は、AI が現実世界と対話するためのインターフェースです。主な種類とその役割は以下の通りです。

• DB MCP: リアルタイムのデータベーススキーマを自動読み込みます。これにより、AI が存在しないフィールドを指定して SQL を生成するミスを防ぎ、正確なクエリを作成できます。
• Knowledge Base MCP: チーム内のドキュメントをマウントします。AI に業務コンテキストと専門用語の理解を与え、より文脈に即した回答を可能にします。
• API MCP: 外部サービスのインターフェース定義をリアルタイムで照会します。マイクロサービス間の連携時に、パラメータの整合性を確保し、エラーを減らします。
• 运维 MCP: CI/CD や監視システムに接続します。AI が直接ビルドのトリガーやログの確認、アラートの分析を行えるようになります。

Skills（エージェントスキル）—— 領域専門家の経験封装

Skills は、業務ロジック、ドメイン知識、そして実行 SOP（標準作業手順書）をパッケージ化したものです。これにより、AI は「何でも少しできる」状態から、「特定の分野の専門家」として振る舞えるようになります。

• ツール接続型: 内部ツールの接続規範を封装します。例：rainbow-config では、七彩石設定センターへの標準的な接続フローを実装しています。
• コード生成型: 特定パターンのコード生成ロジックを固定化します。チームのアーキテクチャ規範に基づき、CRUD モジュールやミドルウェア接続コードを自動生成します。
• メタスキル型: AI 自身に拡張能力を持たせます。例：skill-creator は、既存のコードをもとに新しい Skill を作成する方法を AI に教えます。
• 検索発見型: コミュニティから利用可能な機能を探します。例：find-skills は、80,000 以上のスキルライブラリから必要な機能を検索してインストールします。

知識ベース（Knowledge Base）—— 業務コンテキストの注入

知識ベースは、AI を「汎用モデル」から「業務に精通したアシスタント」へと進化させる鍵です。チーム内のドキュメントやコードリポジトリ、業務資料をマウントすることで、AI は会話時に自動的に業務コンテキストを取得し、推測を減らして実作業に集中できます。

• iWiki ドキュメント庫: チームの Wiki スペースを接続します。業務規範、技術方案、API 文書をマウントし、AI が回答する際にこれらを自動引用します。
• コード庫知識: 工蜂 Git リポジトリを接続します。公共コンポーネント（tRPC や七彩石 SDK など）のマウントにより、生成されるコードが正しい用法に従うようにします。
• AI Wiki: コード庫から自動的に構造化された知識ドキュメントを生成します。これにより、プロジェクトのアーキテクチャやモジュールのロジックを素早く理解できます。
• カスタムファイル: Markdown、PDF、txt 形式のファイルをアップロードします。要件定義書、設計図、議事録などを追加し、AI にプロジェクトの背景知識を与えます。

知識ベースの活用方法

1. 明示的引用: 会話内で @KnowledgeBase と入力して、特定の知识库を選択・参照します。
2. 自動引用: 自動参照スイッチをオンにすると、AI が会話中に自動的に関連知識を検索・参照します。
3. チーム共有: Knot プラットフォームを通じて、組織やチーム全体で知识库 を共有し、業務認識の統一を図ります。

核心となる比喩

MCP は「扉を開ける鍵」であり、Skills は「開いた後に行うべきこと」、知識ベースは「入る前に読む説明書」です。これら 3 つはどれが欠けても成り立ちません。MCP がなければ AI は閉鎖された環境で独善的に作業し、Skills がなければ鍵を持っていても何をしていいか分からない状態になります。また、知識ベースがなければ、部屋に入っても業務の文脈を理解できず、適切な判断ができないのです。

支柱三：実行オーケストレーションとマルチエージェント協働

課題は、AI に無秩序にコードを書かせるのではなく、手順通りに作業を進めさせる方法と、複数のエージェントが役割を分担して複雑なタスクを完遂させる仕組みです。

実行オーケストレーションとは、単に「プランニング型」と「エージェント型」のどちらを選ぶかという選択の問題ではありません。それは、マルチエージェントが協働するための標準化されたワークフローを指します。チームは「3+1 フェーズ」のプロセスに従うべきで、各フェーズには異なる役割を持つエージェントが担当します。

「3+1 フェーズ」標準化ワークフロー：

各エージェントの役割定義：

実際の運用では、以下の通り役割を分担します。

• Planner 役として Plan モードを活用し、システム設計分析や大規模タスクの分解を行う
• Generator 役として Agent モードを活用し、具体的な機能の実装を自動化する
• Evaluator 役として AI Code Review を活用し、リリース前の品質保証を担当する

SDD（Specification Driven Development）ワークフローに従うことが重要です。具体的には、「requirements.md → 人間の審査 → task.md → 実行 → アーカイブ」という流れです。

また、すべてのタスクには明確な「完了基準（Acceptance Criteria）」を定義する必要があります。

支柱四：ステータスとメモリ

問題：長期的な開発プロセスにおいて、AI の出力を一貫性のあるものにするにはどうすればよいでしょうか？

記憶のタイプと実装方法、そしてそのライフサイクルは以下の通りです。

短期記憶は「現在のセッションコンテキスト」に依存し、単一の会話内で有効となります。中期記憶は「Memories（メモリーズ）」機能を活用し、複数のセッションを跨いで情報を永続化します。長期記憶は Git リポジトリ内の Spec ファイルによって管理され、プロジェクトの全ライフサイクルを通じて保持されます。さらに、変更履歴は「Spec Deltas（changes ディレクトリ内）」として記録され、個々の変更サイクルに対応します。

実際の運用では、Git を用いて規範の変更を記録し（Spec Deltas）、これをプロジェクトの長期記憶として蓄積します。また、Memories 機能を活用して AI にプログラミングの習慣やプロジェクト情報を学習させます。さらに、各変更がアーカイブされるたびに、自動的に .codebuddy/plan/ ディレクトリ内の記録を更新する仕組みを構築します。

支柱五：評価と観測（Evaluation & Observability）

問題：AI が生成したコードの信頼性をどう検証すればよいでしょうか？

評価は以下の 4 レベルで実施されます。

• L1（構文レベル）: コンパイルの成功と Lint チェック。ツールには go build や golangci-lint を使用します。
• L2（ロジックレベル）: ユニットテストの通過。go test や自動生成されたテストケースで検証します。
• L3（規範レベル）: Rules による制約への準拠。AI が自動的にコンプライアンスチェックを行います。
• L4（アーキテクチャレベル）: 既存の設計を破壊しないこと。人間と AI が共同でレビューを実施します。

実際の運用では、AI を活用したコードレビュー（CR）を導入し、マージ前に自動で規範への準拠を確認します。また、コーディング完了後に自動的にコンパイルと基礎的な自己テストを行い、検証の闭环を形成します。影響度の高い変更に対しては、自動的に変更ログを生成する仕組みも用意します。

支柱六：制約と回復（Guardrails & Recovery）

問題：AI が権限を超えた操作を行わないようどう防止し、万が一エラーが発生した場合はどう迅速に復旧すればよいでしょうか？

制約は以下の 3 つのレベルで定義されます。

┌──────────────────────────────────────────┐

│ 硬性红线（Rules - 不可违反） │

│ "所有 API 必须包含 Swagger 注解" │

│ "禁止在 Controller 层编写业务逻辑" │

│ "所有数据库查询必须使用 Repository 模式" │

├──────────────────────────────────────────┤

│ 软性约束（Skills - 推荐遵循） │

│ "优先使用项目已有的工具类" │

│ "日志格式遵循团队统一标准" │

├──────────────────────────────────────────┤

│ 安全策略（Safety - 兜底保护） │

│ "涉及数据库变更，优先生成 SQL 脚本" │

│ "高风险操作前自动检测影响范围" │

│ "重要操作自动备份" │

└──────────────────────────────────────────┘

回復メカニズム：

すべての変更は Git で管理し、いつでもロールバック可能にします。

Spec Deltas メカニズムにより、変更の追跡を確実に保証します。

コンパイル失敗時には自動的に直前の安定状態へ自動復元されます。

1.4 Harness の 6 つの柱とツールチェーンのマッピング総覧

以下で具体的なツール規範について詳しく解説します。

二、AI コーディングの統合アーキテクチャ

Harness Engineering の 6 つの柱に基づき、本章ではこれらを一つの完全なアーキテクチャとして具体化します。このアーキテクチャは「人間のアイデア」から「実行可能なコード」に至るまでの全工程を定義しており、チームにおける AI 支援開発の技術的ブループリントと言えます。

端的に言えば、AI は孤立したコード生成ツールではなく、エンジニアリング体系の中に組み込まれた一つのノードです。アーキテクチャの各層は Harness の各柱に対応しており、AI が制約の中で作業を行うことを保証します。

2.1 アーキテクチャ全体図

開発実践において、私たちは AI コーディングの全体像を整理し、上から下へ 5 つのレイヤーで構成されるアーキテクチャを策定しました。それは「入力層」→「ワークステーション (CodeBuddy)」→「基盤サポート (MCP)」→「出力層」→「メトリクス層」です。データは上から下へと流れ、クローズドループを形成します。

各レイヤーの役割は以下の通りです。

データのフローについては以下に詳述します。

人的思考 → [入力層] →構造化された入力

↓

[設定センター] で制約を読み込み、[モードエンジン] が戦略を選択

↓

[エージェントコア] がタスクを実行

↓ ↓

[MCP レイヤー] で外部データを取得 [出力層] で成果物を納品

↓

[計測層] で効果を定量化 → フィードバックによる改善

注意すべきは、これが単なる一方向の生産ラインではない点です。これは閉じたループを形成しています。計測層で得られたデータは設定センターにフィードバックされ、ルールやスキルの継続的な改善を促します。例えば、バグ発生率が上昇したと検知された場合、チームは新たなルール制約を追加するか、既存のスキルを最適化する必要があるかどうかを確認すべきです。

第二部分：実装への落とし込み

以上の二章で、Harness Engineering の核心理念と AI コーディング統合アーキテクチャの設計図について解説しました。「なぜ」と「何」を理解した今、最も重要なのは「どうするか」です。

本パートでは、チームの日常開発にどのようにしてこの規範を落とし込んでいくかを段階的に説明します。各セクションには具体的な手順、設定例、そして验收基準（受け入れ基準）が含まれており、メンバーがこれに従って実行すればすぐに運用を開始できます。

三、実装ロードマップ（3 段階の漸進的アプローチ）

規範の導入は一夜にして成し遂げられるものではありません。プロセスを明確な目標と验收基準を持つ三つのフェーズに分割しました。

四、第 1 段階：基盤構築（迅速な立ち上げ）

目標：チーム全員が AI コーディングツールを活用し、基本的な制約体系を確立する。

4.1 CodeBuddy のインストールと設定

4.1.1 IDE プラグインのインストール

VSCode へのインストール:

• CodeBuddy 公式サイトからプラグインの .vsix ファイルをダウンロードします。
• VSCode を開き、Extensions（拡張機能）→ ... → Install from VSIX から、ダウンロードしたファイルを選択してインストールします。
• Command(⌘) + L または Ctrl + L を押下し、画面下部に CodeBuddy のアイコンが表示されればインストール成功です。
• アカウントにログインし、Plan モードとエージェントモードの両方が正常に動作するか確認してください。

JetBrains シリーズ IDE へのインストール（GoLand, PyCharm, IDEA など）:

• CodeBuddy 公式サイトから JetBrains 用プラグインの .zip ファイルをダウンロードします（※ダウンロード後、解凍しないでください）。
• IDE を開き、Plugins → ⚙️ → Install Plugin from Disk から、ダウンロードした .zip ファイルを選択してインストールします。
• 画面下部に CodeBuddy のアイコンが表示されればインストール成功です。
• アカウントにログインし、チャット機能が正常に動作するか確認してください。

⚠️ Mac の Safari ブラウザでは、デフォルトでダウンロードした zip ファイルが自動的に解凍される場合があります。Safari の設定から「ダウンロード後に安全なファイルを自動的に開く」機能を無効化することをお勧めします。

4.1.2 CLI ツールのインストール（オプション）

社内ではすでに3 つの最高峰 CLI プログラミングツールが統合されており、用途に応じて使い分けることができます。

CLI ツール | インストールコマンド | 起動コマンド | 設定ディレクトリ

---|---|---|---

Claude Code Internal | npm install -g --registry=https://xxx.com/ | claude-internal | ~/.claude-internal/

Gemini CLI Internal | npm install -g --registry=https://xxx.com/gemini-internal | gemini-internal | ~/.gemini/

Codex CLI Internal | npm install -g --registry=https://xxx.com/codex-internal | codex-internal | ~/.codex-internal/

事前の依存関係として、Node.js 20 以降が必要です。これら3 つは業界で最も優れた AI コーディングツールであり、個人の使い勝手に合わせてお選びください。

4.1.3 CodeBuddy の核心設定

インストール完了後、CodeBuddy の最大限の効果を発揮させるために、以下の核心設定を行ってください。

1. モデルの選択

ダイアログボックスの左下でモデルを切り替えます。推奨戦略は以下の通りです。

⚠️ セキュリティに関する注意：Claude、GPT、Gemini などの外部モデルはコードの文脈を外部へ送信します。機密性の高い業務では、必ず内部デプロイされたモデルを使用してください。

1. Memories（記憶機能）の設定

Memories を使用すると、CodeBuddy はあなたのコーディング習慣やプロジェクト情報を記憶し、セッションを超えて永続化できます。

有効化方法：

• CodeBuddy の設定ページで「Memories」オプションを選択します。
• Memories スイッチがオンになっていることを確認します。

手動での記憶登録：

Agent モードの対話中で、CodeBuddy に直接覚えてほしい情報を伝えます。

请记住：
1. 我习惯使用 Go 语言开发，项目使用 gin 框架
2. 代码注释使用中文
3. 变量命名使用 camelCase 风格
4. 所有 API 返回统一使用 pkg/response 包的标准格式管理记忆：在 CodeBuddy 设置页面 → Memories，可以查看、编辑、删除已保存的记忆。

1. Commands（コマンド）の設定（指示型インタラクション）

Commands は、頻繁に発生する開発タスクを再利用可能なコマンドとしてパッケージ化する機能です。本質的には「素早くトリガーできる標準化されたプロンプト」です。

Command の作成方法：

• ダイアログボックスで / を入力し、「新規 Command」を選択します。
• Command 名を入力します（英語での命名を推奨）。
• Command 内容（つまり、事前設定されたプロンプト）を入力します。

チームで推奨する Commands：

/init Command のサンプル内容：

このコードベースを分析し、.codebuddy/rules ディレクトリに global.md ファイルを作成してください。このファイルは、同様のコードベースで動作する今後の CodeBuddy インスタンスで使用されます。

追加すべき内容は以下の通りです。

1. 頻繁に使用するコマンドの記載（ビルド方法、コードチェックの実行方法、テストの実行方法など）
2. コードアーキテクチャと構造の高レベルな概要。特に「マクロ」視点での設計に焦点を当ててください。

利用上の注意：

• 既にファイルが存在する場合は、その内容を改善してください。
• 一般的な開発プラクティスについては記載不要です。
• ファイルの冒頭には、必ず以下のメタデータを含めてください：

CodeBuddy Rules

type: always

⚠️ 验收标准：每位团队成员能在 IDE 中正常唤起 CodeBuddy 对话框，Token 使用量正常，能展示一个简单项目实现的 prompt。

4.2 team-harness リポジトリの作成

これはチーム規範における唯一の信頼できる情報源です。すべての Rules、Skills テンプレート、AGENTS.md テンプレートをここに集約して管理します。

ステップ 1：リポジトリ構造の初期化

リポジトリの作成

mkdir team-harness && cd team-harness

git init

標準的なディレクトリ構造の作成

mkdir -p rules/{global,golang,python,frontend}

mkdir -p skills/{common,business}

mkdir -p templates

mkdir -p docs

コアファイルの作成

touch rules/global/base.md

touch rules/golang/go-backend.md

touch templates/AGENTS.md

touch templates/project.md

touch README.md

最終的なディレクトリ構造：

チームハルネスディレクトリ構成

team-harness/

├── rules/ # チームルール集積

│ ├── global/ # グローバル共通ルール

│ │ └── base.md # 基本規範（全プロジェクトで必須）

│ ├── golang/ # Go言語専用ルール

│ │ └── go-backend.md

│ ├── python/ # Python専用ルール

│ └── frontend/ # フロントエンド専用ルール

├── skills/ # チームスキル集積

│ ├── common/ # 共通スキル

│ │ ├── skill-creator/ # スキル作成ツール

│ │ └── find-skills/ # スキル検索ツール

│ └── business/ # ビジネス特化スキル

│ └── rainbow-config/ # レインボー構成（七彩石）連携

├── templates/ # テンプレートファイル

│ ├── AGENTS.md # AI 運用マニュアルテンプレート

│ └── project.md # プロジェクト記述テンプレート

├── docs/ # 利用ドキュメント

│ └── onboarding.md # 新規メンバー向けガイド

└── README.md

ステップ 2：同期スクリプトの作成

ビジネスプロジェクト内で、最新規範を自動取得するスクリプトを実装します。

#!/bin/bash

sync-harness.sh - チーム規範を現在プロジェクトへ同期

HARNESS_REPO="git@xxx.com"

HARNESS_DIR=".harness-upstream"

最新規範の取得

if [ -d "$HARNESS_DIR" ]; then

cd $HARNESS_DIR && git pull && cd ..

else

git clone $HARNESS_REPO $HARNESS_DIR

fi

Rules をプロジェクトへ同期

mkdir -p .codebuddy/rules

cp $HARNESS_DIR/rules/global/*.md .codebuddy/rules/

cp $HARNESS_DIR/rules/golang/*.md .codebuddy/rules/ # 言語別に選択してコピー

Skills をプロジェクトへ同期

mkdir -p .codebuddy/skills

cp -r $HARNESS_DIR/skills/common/* .codebuddy/skills/

echo "✅ チーム規範の同期が完了しました"

ステップ 3：CI による自動同期の設定（オプション）

プロジェクトの CI パイプラインに自動同期プロセスを追加し、ビルド実行前に常に最新規範を反映させます。

4.3 Rules 設定（グローバルおよびプロジェクトレベルでの制約）

Rules は、AI が各インタラクションで必ず読み込むグローバル制約であり、いわば AI が遵守すべき「法」です。CodeBuddy では 3 つの階層で Rules を定義できます。

4.3.1 Rules の階層体系

階層構造と適用範囲

AI コーディング支援ツール「CodeBuddy」のルールは、適用範囲と設定方法によって以下の 3 つに分類されます。

User Rules（ユーザールール）

• 対象: 全プロジェクト（個人利用）
• 設定場所: CodeBuddy の設定ページ → Rules
• 動作: 会話ごとに自動的に適用される

Team Rules（チームルール）

• 対象: チーム内の全メンバー
• 管理方法: Knot プラットフォームから一元的に配布
• 動作タイプ: always（常時適用）または manual（手動指定）で設定可能

Project Rules（プロジェクトルール）

• 対象: 単一プロジェクトのみ
• 保存場所: .codebuddy/rules/ ディレクトリ内の .md ファイル
• 動作: 常時適用、または会話時に @Rules で手動参照

4.3.2 ユーザールールの設定方法

1. CodeBuddy の対話パネルにある設定アイコン（歯車）をクリックします。
2. Rules 設定ページへ移動し、個人向けのルールを追加します。プラットフォームが用意したテンプレートを利用すれば、素早く作成して微調整も可能です。

個人ルールの例

1. 回答は日本語で行うこと
2. コードのコメントは日本語で記述すること
3. Go の標準ライブラリを優先使用すること
4. 変数名は camelCase（キャメルケース）形式にすること

4.3.3 チームルールの設定方法（Knot プラットフォーム経由）

チームルールは、管理者が Knot プラットフォームで一元管理・配布します。これにより、全メンバーが統一された開発基準に従うことが保証されます。

設定手順

1. Knot の Rules 管理ページへアクセスします。
2. 「新規 Team Rule」ボタンをクリックします。
3. ルール内容を入力します。必須項目として、ヘッダー部に以下の形式で Rule Type Header を含める必要があります。

---
type: always
---
# チーム Go 後端開発規範
## アーキテクチャ制約
1. 階層アーキテクチャを厳守：Controller → Service → Repository → Model
2. Controller レイヤーでのビジネスロジック記述は禁止
...

1. 申請を送信し、承認されれば Team Rule は自動的に有効化されます。
2. チームメンバーの CodeBuddy は、有効化された Team Rules を自動的に読み込みます。

💡 ヒント: Team Rule の type には、「常時適用」の always と「手動参照」の manual の 2 モードが用意されています。

4.3.4 プロジェクトルールの設定方法

作成手順

1. CodeBuddy の対話パネルで「新規 Project Rule」をクリックします。
2. ルール内容を入力してください。ヘッダーのメタデータは変更しないよう注意が必要です。

適用範囲の設定

• 常時有効: 会話ごとに自動的に読み込まれます。
• 手動指定: 会話時に @Rules を使用して選択する必要があります。

Rules ファイル構造の規範

Go 言語によるバックエンド開発の通用規範

一、アーキテクチャ制約（絶対的なルール）

1. レイヤー構造を厳守する：Controller → Service → Repository → Model の順で構成すること。
2. Controller レイヤーでの業務ロジックの実装は禁止。Controller はパラメータの検証とレスポンスの封入のみを担当する。
3. すべてのデータベース操作は Repository レイヤーを経由し、Service 層で直接 SQL を記述することは禁じられている。
4. 外部公開 API には必ず Swagger アノテーションを付与すること。

二、コードスタイル

1. 関数やメソッドには、その用途を示す簡潔なコメントを必ず記載する。
2. エラー処理において「_」で無視することは許されない。明示的な処理を行うか、上位へエラーを伝播させること。
3. 変数名は camelCase を、定数は ALL_CAPS を使用する。
4. 単一の関数の行数は 80 行以内とする。これを超えた場合は分割すること。

三、セキュリティ戦略

1. データベースの変更を行う際は、直接実行するのではなく、まず SQL スクリプトを生成することを優先する。
2. ファイルの削除や移動には追加の確認は不要だが、データベース構造の変更については必ず確認プロセスを経ること。
3. すべての機密設定（シークレットキー、接続文字列など）は設定センターから読み込むこと。ハードコーディングは厳禁である。

四、開発行動指針

1. 新機能の実装前には既存のコードベースを分析し、可能な限り既存モジュールを流用すること。
2. コード変更範囲は最小限に抑え、1 つの PR で解決できるのは 1 つの問題に限る。
3. すべての変更には明確なコミットメッセージを付与する。
4. 新機能の実装時には、必ず同時にユニットテストも作成すること。

Rules の保存と再利用フロー

業務プロジェクトの team-harness リポジトリにおける開発者向けフロー：

1. Rules の変更を PR として提出する。
2. チームによるレビューとマージを行う。
3. 各業務プロジェクトへ自動的に同期される。
4. .codebuddy/rules/ ディレクトリが更新される。

AI は次回の対話時に新しいルールを自動的に読み込みます。

Rules の有効性を検証するには、CodeBuddy で以下のようにテストしてください：

「你好，请告诉我当前加载了哪些 Rules？」（現在ロードされている Rules を教えてください）

AI は認識した上で、ロード済みのルールファイルを列挙して回答するはずです。

4.4 AGENTS.md の作成

AGENTS.md は AI 向けの「取扱説明書」です。長さは約 100 行以内に抑え、詳細なドキュメントへの索引として機能させます。

プロジェクトのルートディレクトリに AGENTS.md ファイルを作成してください。

AI 開発アシスタント利用ガイド

プロジェクト概要

本プロジェクトは [プロジェクト名] です。Go を基盤としたマイクロサービスアーキテクチャを採用し、[フレームワーク名] フレームワークを使用しています。

アーキテクチャ構成

• レイヤー構造：Controller → Service → Repository → Model
• 詳細なアーキテクチャドキュメントについては、docs/ARCHITECTURE.md を参照してください。

ディレクトリ構成

• internal/ - ビジネスロジック（サービスごとにサブディレクトリを分割）
• pkg/ - 共通ユーティリティライブラリ
• api/ - API 定義（Proto/Swagger）
• configs/ - 設定ファイル
• scripts/ - スクリプトツール集

開発規約

• コーディング規約：.codebuddy/rules/go-backend.md を参照してください。
• データベース運用：すべてのクエリは Repository レイヤーを経由すること。
• エラー処理：エラーは必ず pkg/errors でラップして統一する。

頻出コマンド

• ビルド：go build ./...
• テスト実行：go test ./...
• Lint 実行：golangci-lint run

進行中の要件

• 詳細は .codebuddy/plan/ ディレクトリ内のアクティブなタスクを確認してください。

注意事項

• 新機能を実装する際は、まず pkg/ に再利用可能なツールがないか確認すること。
• データベースの変更には、必ず事前に SQL スクリプトの生成が必要である。
• API の変更がある場合は、Swagger ドキュメントの更新を必須とする。⚠️ AGENTS.md は目次索引であり、百科事典ではありません。AI が必要な場合にのみ詳細ドキュメントへ深入りできるよう、簡潔に保つようにしてください。

4.5 知識ベース設定（実践ガイド）

知識ベースは、AI に業務コンテキストを持たせるための核となる手段です。チーム内のドキュメントやコードライブラリ、専門知識をマウントすることで、AI は「汎用的な知能」から「貴社の業務に精通した専門家」へと進化します。

4.5.1 知識ベースの種類と適用シーン

設定場所: Knot プラットフォーム（iWiki、工蜂、カスタムファイル）、CodeBuddy 内蔵機能（AI Wiki）

4.5.2 Knot プラットフォームでのチーム共有知識ベース作成

ステップ 1：知識ベースの作成

Knot の知識ベース管理ページへアクセスし、「知識ベースの追加」をクリックします。その後、以下のいずれかのタイプを選択して情報を記入してください。

• iWiki タイプ: iWiki スペースのアドレスを入力
• 工蜂コードベースタイプ: Git リポジトリのアドレスとブランチを指定
• カスタムファイルタイプ: Markdown, TXT, PDF ファイルをアップロード

ステップ 2：共有範囲の設定

知識ベースの詳細ページで「共有スイッチ」をオンにし、対象となる組織またはチームを選択します。送信後、管理者による承認待ちとなりますが、承認されればチーム共有が完了します。

ステップ 3：データソースの構成

知識ベース内の「データソース設定」ページでは、複数のデータソースを組み合わせることが可能です。

• 要件: TAPD プロジェクトに対応
• コード: 工蜂 Git リポジトリ（アドレスとブランチを入力）に対応
• ドキュメント: iWiki スペースに対応
• 可観測性: 智研プロジェクトに対応

4.5.3 CodeBuddy での知識ベース有効化

ステップ 1：設定画面へ移動

CodeBuddy の会話パネルで設定アイコンをクリックし、「知識ベース」オプションへ進みます。

ステップ 2：知識ベースの起動

知識ベースリストから、必要な公共知識ベースおよび個人用知識ベースをオンにします。また、「自動参照スイッチ」も推奨設定として有効化しておきましょう。これにより、AI が関連する知識を自動的に参照できるようになります。

ステップ 3：知識ベースの活用方法

方法 1：明示的な参照（精密な制御）

会話の入力欄で「@KnowledgeBase」と入力し、特定の知識ベースを選択します。

例：@チーム技術ドキュメント 現在のプロジェクトにおけるキャッシュ戦略は適切でしょうか？分析をお願いします。

方法 2：自動参照（手間なし）

自動参照機能をオンにすると、AI が質問に応じて自動的に関連知識を検索してくれます。

例：ユーザー認証モジュールを実装してください。既存の認証方式（バージョン 4.5.4）を参考にしてください。

4.5.4 AI Wiki の開設（推奨）

AI Wiki はコードベースから自動生成される構造化された知識ベースで、チームメンバーがプロジェクトアーキテクチャを素早く理解するのを支援します。

• CodeBuddy の右上メニューから「AI Wiki」を開く
• 案内に従って現在のコードベースに AI Wiki を開設（インデックス化は通常 24 時間以内に完了）
• 開設後は IDE 内でプロジェクトドキュメントを閲覧可能。ファイルをクリックするとソースコードへジャンプします。
• @AIWiki と入力して質問することで、プロジェクトのモジュールロジックを素早く把握できます。

4.5.5 チーム向け推奨知識ベース一覧

⚠️ 受入基準