コントリビューション
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/contributing/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
Ankole にコントリビュートする際は、コードを書き始める前にまず 2 つの基本ドキュメントを読み、そこで定められた手順に沿って作業を進めます。このページはその全体像を示すガイドマップであり、正本となるドキュメントの場所と一連の流れを案内します(内容を二重管理するものではないため、万が一このページと正本ドキュメントの記述に食い違いがある場合は、常に正本ドキュメント側が優先されます)。
最初に強調しておきたいのは、Ankole のコントリビューションルールは単なる「推奨マナー」ではないという点です。コードレビューと、プロダクトコードを変更するすべてのコミットに課される changelog チェックによって厳格に運用されています。AGENTS.md と CONTRIBUTING.md を読まずに提出された変更は、まずそれらを読んでやり直すよう差し戻されるため、作業前に必ず目を通してください。
ルールを所有する 2 つのドキュメント
AGENTS.md— プロジェクト全体の設計・実装原則を定めたドキュメントです。作業スコープと権限、changelog の記載ルール、最小の正しい変更、意図したユーザー体験と運用要件を満たす範囲での Worse is Better、目的への忠実さ、各サブシステムの責務境界が定義されています。「変更をどのように設計・実装するか」はここで決まります。CONTRIBUTING.md— 開発からマージまでの実務手順を定めたドキュメントです。6 ステップのローカル環境構築、Feishu を使ったエンドツーエンド受け入れ確認、トラブルシューティング手順、リポジトリ構成図、品質ゲート、changelog および PR の作成ルールがまとまっています。「変更をマージさせるために何をすべきか」はここで決まります。
それぞれの領域において、この 2 ファイルが唯一の正本(source of truth)です。本ページを含む他のドキュメントはすべてこれらを参照しており、上書きすることはありません。
セットアップの道筋(6 ステップ)
ローカル環境の構築手順は CONTRIBUTING.md に 6 つのステップとして定義されています。作業を始める前に全体像をつかめるよう、概要を以下に示します。
- リポジトリを取得し、開発環境を選ぶ — リポジトリをクローンし、macOS / Linux / WSL2 または GitHub Codespaces を用意します。
- システムツールを導入して確認する —
bash tools/devkit/scripts/env-setup.shを実行し、bun、elixir、rustc、cargo clippy、dockerがすべて正常に動作することを確認します。各kitコマンドの詳細は kit CLI reference を参照してください。 - 依存パッケージを導入し、ローカルサービスを初期化する —
bun install、bun run services:start(PostgreSQL 18 とFunction Runtime/ankole-function-runtimeの起動)、およびbun run control-plane:setupを順に実行します。 - 開発環境全体を起動する —
bun devを実行します。 - 製品の初回セットアップを完了する —
/setupを開いてアクティベーションを行い、パスワードレスの SMTP Email OTP または Feishu アプリ OAuth で最初の管理者としてサインインします(Feishu の完全なエンドツーエンド受け入れ確認を行う場合は Feishu のテストアプリを作成します)。その後、/site-admin-consoleの Site Admin Console でランタイム設定を行います。 - エンドツーエンドの往復動作を確認する — 実際に Feishu からメッセージを送り、Agent に届いて期待どおりの返信が返るところまで確認します。
ブラウザーで画面が開いただけではセットアップ完了とは言えません。実際のメッセージが往復して初めて環境構築が完了します。最短手順は Quick start を、開発者向けの完全な受け入れ手順は CONTRIBUTING.md を参照してください。
変更の仕方
最初の編集を行う前に AGENTS.md を確認してください。特に頻繁に関わる原則は次のとおりです。
- スコープと権限: 質問への回答、調査、計画立案を求められた場合は読み取り専用で作業し、実装を求められた場合にのみファイルを編集します。事前承認なしに依頼範囲外のスコープへ手を広げないでください。
- ユーザーと運用者のための changelog: プロダクトの挙動に関わるコミットでは、ルートの
CHANGELOG.mdにバージョンを 1 つ追加し、アップグレード後に利用者や運用者が気づく変化を記述します(ドキュメントのみの変更ではバージョンを追加しません)。詳細は次節を参照してください。 - 最小の正しい変更: 定まった方針に従い、システムが維持すべき契約を守ったうえで、読み手が理解しやすい最小限の変更にとどめます。複雑な共通抽象化を導入するくらいなら、少々のコード重複を許容する方が健全です。
- Worse is Better: 意図したユーザー体験と運用要件を満たす最も単純な実装を選びます。周辺的な未対応ケースでは、限定した契約、明示的な拒否、手動復旧も適切な選択です。
- 目的への忠実さ: 手軽な代替案でお茶を濁さず、求められた本来のゴールを実現します。単にテストをグリーンにすることが目的ではなく、本来の担当モジュールと契約を通る正しい経路を動かすことが目的です。
- サブシステム境界の厳守: 永続データは PostgreSQL、永続状態の管理とプロセス監視は Elixir control plane、共有ネイティブ処理と通信基盤は Rust kernel、Agent ごとのツール実行環境は Bun Agent Computer Worker、そしてステートレスな Applet バックエンド関数や決定論的プログラムの isolate 実行は
Function Runtime(app/function_runtime/)がそれぞれ担います。複数の層にまたがる変更では、近道をせずこれらの責務境界を守ってください。
changelog ルール
プロダクトコードに触れるすべてのコミットで必須となるゲートであり、初めてのコントリビューションで最もつまずきやすいポイントです。CONTRIBUTING.md の規定は次のとおりです。
- ルートの
*.md、docs/、app/website/、またはCHANGELOG.mdのみを変更するコミットでは、バージョンを追加しません。それ以外のmainへのコミットでは、ルートのCHANGELOG.mdの先頭に未リリースのバージョン節を 1 つ追加または更新します。未コミットのバージョン見出しがすでにある場合は、その節に追記します。FOSS に影響せずinternals/内で完結する変更はinternals/CHANGELOG.mdに記載します。 - 記載するのは、アップグレード後にユーザーや運用者の目に見える変化だけです(新機能、仕様変更、機能の削除、遭遇し得た不具合の修正、必要な手動対応など)。ドキュメント修正、テスト追加、開発ツール、依存ライブラリ更新、内部リファクタリングは列挙せず、外から見える変化がない場合は
Internal changes only.とだけ記述します。 - バージョン番号は
MAJOR.MINOR.PATCH形式を使い、通常はPATCHを上げます。これまで製品になかった新機能の追加や、利用者側の対応を伴う破壊的変更がある場合はMINORを上げます(MAJOR更新やプレリリースサフィックスはメンテナーの判断に従います)。
ルートの CHANGELOG.md はFOSS の更新履歴であり、そのままリリースバージョン単位としても機能します(別のリリースノートファイルはありません)。main ブランチのビルドワークフローで 3 つのランタイムイメージ(ankole-control-plane、ankole-agent-computer、ankole-function-runtime)すべての検証が通ると、最新バージョン番号がこれら 3 イメージのタグとして付与され、該当セクションの記述からそのまま不変の GitHub Release が自動作成されます。後回しにする事務作業ではなく、コード変更そのものの一部として書いてください。
正しいチェックを実行する
どの変更でどの検証を回すべきかは CONTRIBUTING.md に、各コマンドの使い方は kit CLI reference に記載されています。基本の流れは次のとおりです。
- 変更したパッケージの単体テストと静的解析 — 全テストを闇雲に回すのではなく、影響を受けるパッケージに対象を絞って実行します。
- 影響範囲の統合テストおよびエンドツーエンドテスト — プロセス間通信、外部 provider、再起動を伴う永続化、またはユーザー操作フローをまたぐ変更では省略せず実行します。
bun run analyze(kit analyze all) — リポジトリ全体のコードスメル、未使用コード、モジュール構造、循環依存を検査します。- コミット前の
bun run lintとbun run fmt:check— スタイルとフォーマットの整合性を確認します。
手元の環境制約によって必須チェックの一部を実行できなかった場合は、実行できなかった正確なコマンド名と理由を正直に報告してください。未実行のチェックを「検証済み」として提示してはいけません。
プルリクエストを提出する
PR 提出の詳細も CONTRIBUTING.md にまとまっています。要点はシンプルです。各コミットが changelog ルール(プロダクト変更 1 コミットにつき 1 バージョン)を満たしていること、AGENTS.md の責務境界を守っていること、そして PR の説明文で「何を変更し、なぜその設計にしたか」をプロジェクトの用語に沿って明確に説明することです。レビューでもまさにこの点が確認されます。
このガイドがそうでないもの
このページは AGENTS.md や CONTRIBUTING.md の要約版として代わりに読むものではなく、両ドキュメントへの案内口です。AGENTS.md はすぐに読み切れる分量に絞られているため、編集前に必ず原文を一読してください。また、すでに確定している設計原則はトレードオフを踏まえたうえでのプロジェクトの意思決定ですので、個人の好みではなく「確立された方針の中で一貫性のある実装になっているか」という観点で変更を組み立ててください。
次のステップ
- コードを編集する前に、まず
AGENTS.mdを読んでください。 - ローカル環境の構築と受け入れテストは
CONTRIBUTING.mdに沿って進めてください。 - 開発用コマンドの詳細については、kit CLI reference を参照してください。
- 変更対象がまたがるサブシステム間の境界については、architecture overview を参照してください。