Imported from kota-kawa/Marmo-Core (
AGENTS.md). Install upstream withnpx skills add kota-kawa/Marmo-Core. Copyright stays with the author.
Marmo-Core Agent Rules
Marmo-Core は、Object Routing を実装する公開 Python ライブラリである。 このファイルは、このリポジトリで作業するエージェント(と人間)の規約をまとめる。
基本方針
- このリポジトリを実装コードの唯一の正とする。
mainは安定版として扱う。PyPI に公開される。- 研究中の新手法は
research/<method-name>ブランチで実装する。 Object-Routing-Researchへ Marmo-Core 本体をコピーしない。評価はそちらから commit SHA を固定して行う。
ドキュメントの参照先
各行は「パス/内容の区分/いつ参照するか、または何に使わないか」の型で書く。
README.md/公開向けの概要・インストール・Quickstart・CLI と.envの使い方/利用者視点の説明を確認・修正するとき。内部設計の正本としては扱わず、実装との差分が見つかった場合は公開向け説明として修正する。ARCHITECTURE.md/レイヤー構成、Kernel.run_goalと CLI のリクエスト経路、契約と境界、拡張ポイントをまとめた内部設計の正本/複数モジュールにまたがる変更では最初に必要な章だけ読む。docs/knowledge/development_conventions.md/プロジェクト構成、ビルド・テストコマンド、実装規約、命名、責務分割、テスト方針、サブエージェントの指定、AI 出力の品質確認/コードを変更する作業では着手前に必ず読む。docs/knowledge/README.md/再利用可能な知見の索引/何か調べる前に該当する知見があるか確認する。作業ログや一時的な状態は追加しない。docs/knowledge/debugging.md/実モデル・検索・CLI・パッケージングの不具合の切り分け手順/動作がおかしいときに、コードを読み始める前に読む。docs/knowledge/contracts-and-compatibility.md/公開 API、リソース定義、状態ファイル、監査ログ、CLI 終了コードの互換性契約と変更手順/これらの表面に触る変更の前に読む。docs/knowledge/parallel_work.md/git worktree で作業を分けた後の運用手順/並行作業をするときに読む。docs/knowledge/lessons_from_history.md/git 履歴と PR から抽出した過去の失敗と教訓/同じ轍を踏まないために、該当領域を触る前に読む。docs/decisions/README.md/重要な技術判断(ADR)の索引/判断を変更・追加するときは既存 ADR を確認し、理由と影響を更新・記録する。docs/threat-model.md/信頼境界・想定脅威・リリース前レビューの記録/権限、副作用、ポリシー、シークレット、HITL に触る変更で読み、境界を動かしたら更新する。docs/connectors.md、docs/local-resource-packages.md/利用者向けマニュアル/実装の責務や内部挙動を確認する資料としては使わない。benchmarks/README.md/ベンチマークの実行方法、シナリオ設計、測定結果と読み方/検索・選択・ルーティングの挙動を変えるときに、比較の基準として読む。数値は隣のbenchmarks/results/*.jsonの同一実行から取る。CONTRIBUTING.md/公開向けの開発環境構築、CI の再現、リリース手順/外部コントリビューターに見せる手順を確認・修正するとき。SECURITY.md/脆弱性報告の窓口とスコープ/セキュリティ報告の扱いを確認するとき。CHANGELOG.md/リリースごとの変更履歴(Keep a Changelog 形式)/利用者に見える変更は## [Unreleased]に追記する。過去のパスを含むので、現在のリポジトリ構成の根拠には使わない。.github/BRANCH_PROTECTION.md/mainの保護設定と必須 CI チェックの記録/マージ条件や CI ゲートを確認・変更するときに参照する。.github/PULL_REQUEST_TEMPLATE.md/PR 本文の型/PR を作るときに埋める。要件定義書1.md、改善策.md/初期の要件定義と、2026-09 時点の改善提案メモ/背景を知るための資料であり、現在の実装の説明ではないので、実装判断の根拠として引用しない。実装済みの項目はCHANGELOG.mdで確認する。.claude/RESUME.md/Claude Code のセッション再開用チェックポイント/手で編集せず、内容を作業の根拠にしない。
ドキュメントを追加・削除したら、同じコミットでこの一覧も更新する。文書内のパス参照が存在するかは python3 scripts/check_doc_paths.py が CI で検証する。
ブランチ・コミット・PR
mainへ直接 push しない。すべての変更は作業ブランチにコミットし、PR でmainに取り込む。- ブランチ名は
<type>/<topic>とする。これまでに使われている type はfix、docs、chore、ci、feat、research。研究手法は必ずresearch/<method-name>。 - コミットの件名は既存履歴に合わせて
<type>: <English summary>とする(type はfeat/fix/docs/chore/ci/test/refactor。Dependabot はciを使う)。本文は日本語でも英語でもよい。挙動が変わる修正は、本文に原因・実測値・トレードオフを書く(git logのfix:コミットが手本)。 - 1 つの PR に種類の異なる変更(バグ修正とリファクタリング、機能追加と無関係な整形など)が含まれる場合は、種類ごとに別コミットに分ける。
- PR のタイトルと本文は日本語と英語の両方を含める(PR titles and descriptions must include both Japanese and English)。タイトルは
<type>: <English summary> / <日本語要約>。 - PR 本文は
.github/PULL_REQUEST_TEMPLATE.mdに従い、変更内容、関連 issue(あれば)、テスト(実行したコマンドと結果)、判断が要るところ(既定値・終了コード・スコアの変化など利用者に見える差分)を書く。 - 利用者に見える変更は
CHANGELOG.mdの## [Unreleased]に同じ PR で追記する。バージョン番号を上げるのはメンテナの判断であり、リリースコミットは別に切る(CONTRIBUTING.mdの Releasing)。 - エージェントは、ユーザーから明示的な指示がない限り PR をマージしない。
エージェントの作業ルール
- 作業開始前に現在のブランチと未コミットの変更を確認する。
benchmarks/results/に未追跡の結果ファイルがあることが多い。これは他の作業の成果物なので、触らず、自分のコミットにも含めない。 - ユーザーまたは他のエージェントによる既存の変更を、明示的な許可なく上書き、破棄、巻き戻ししない。
- 要件が曖昧なまま実装コードを書かない。着手前にスコープとスコープ外を合意し、合意していない変更は加えない。未使用のヘルパー、過剰な抽象化、コメントアウトした残骸などの不要なコードも生成しない。
- コメント、docstring、関数名を仕様の根拠にせず、実装本体とテストを読んで判断する。触った範囲で実装と食い違うコメントや名前を見つけたら、同じ変更で直す。
- テスト失敗やレビュー指摘に対する自動修正のループは 5 回を上限とする。超えたら自力で続けず、何が未解決でどこで詰まっているかを添えてユーザーに報告する。
- 実装したエージェントは自分で完了判定をしない。コードを変更する PR は、作る前にレビュー用サブエージェント(指定は
docs/knowledge/development_conventions.mdの「サブエージェントの指定」)へスコープ・差分・チェックリスト(要件を満たす/スコープ外の変更が無い/不要なコードが無い/テストが通る/禁止事項に触れない)だけを渡してレビューさせ、実装担当の意図や経緯の説明は渡さない。ドキュメントだけの変更はこのレビューを省略でき、省略した場合は PR 本文にその旨を書く。指摘は検証してから反映する。指摘に反論がある場合は握りつぶさずユーザーに上げる。 - ユーザーへの説明や、作業・編集途中の経過報告はすべて日本語で表示する。
テストと検証
-
全テストは約 500 件で 10 秒強で終わる。修正中は変更箇所に対応するテストモジュールだけを回してよいが、PR を作る前には必ず CI と同じコマンドで全体を通す:
python -W error::ResourceWarning -m unittest discover -s tests ruff check marmo_core tests scripts tools mypy marmo_core python scripts/release_check.py python scripts/check_doc_paths.py python scripts/check_env_documentation.py check-manifest -
-W error::ResourceWarningは省略しない。CI がこの形で走るため、閉じ忘れたファイルやソケットはアサーションが通っても落ちる。 -
修正には回帰テストを付け、「修正を戻すとそのテストが落ちる」ことを確認する。モック LLM のテストだけでは実プロバイダとの不整合は検出できない(
docs/knowledge/lessons_from_history.md)。 -
追跡ファイルを追加したら
check-manifestを回す。sdist に入れるならMANIFEST.in、リポジトリ専用ならpyproject.tomlの[tool.check-manifest] ignoreに追加する。 -
テストを実行できない場合は、その理由を最終報告に記載する。
AI の出力・ルーティング品質に関わる変更
次の変更は、単体テストが通るだけでは完了にしない。
- プロンプト文言・ツール定義・会話の組み立て・プロバイダのリクエスト形(
kernel.py、compiler.py、planner.py、llm_routing.py、providers.py): 固定したプロバイダ応答によるテスト(tests/test_provider_compat.pyの transport 差し替え方式)で形式とエラー処理を確認し、可能なら実モデル(OpenAI 互換または Anthropic)で変更前後を同じ入力で実行して結果を PR 本文に書く。実モデルの応答は再現しないので、CI の合否条件にはしない。 - 検索・選択・ルーティングのスコアや既定値(
retriever.py、semantic.py、selector.py、graph_routing.py、hierarchy.py、rerank.py、adaptive.py):benchmarks/の該当スイートを変更前後で実行し、指標(hit@k、MRR、recall@k、Set F1、abstain/escalate 精度、レイテンシ)を PR 本文に並べる。第1層の関連度成分を変える場合は、第2層(集合選択)の Coverage と abstain/escalate 精度まで確認する(docs/decisions/0003-absolute-relevance-and-bm25f.md)。 - スコアの尺度を変えたら、ベンチマークスクリプトの既定しきい値と
benchmarks/README.mdの数値を同じ PR で更新する。
手順と限界は docs/knowledge/development_conventions.md の「AI 出力の品質確認」に従う。
サブエージェントと git worktree
サブエージェントと git worktree は別の判断軸である。「作業を独立分割できるか」でサブエージェントを、「作業ツリーを共有すると壊れるか」で worktree を判断する。
- サブエージェントを使う: 読み取りのみの調査・レビュー、または担当ファイルを重複なく分割できる編集。調査・実装・レビューを分けるときは役割ごとに別の担当にし、各担当にはその役割に必要な情報だけを渡し、同じファイルを同時に編集させない。複数の担当に分けるときは、着手前に「誰の成果物を誰にどの形式で渡すか」「何が揃ったら次を始めてよいか」「最終判定は誰か」を決めて依頼文に書く。最終判定はユーザーで、エージェント間の判断の不一致はユーザーに上げる。
- worktree を使う(いずれか該当時): 並列作業が同じ生成物(
CHANGELOG.mdの Unreleased、marmo_core/__init__.pyの__all__、benchmarks/results/*.json、tests/fixtures/compat/)に触る/別 PR に分けるべき変更を同時に進める/破棄する可能性のある大規模リファクタ/作業ツリーにユーザーの未コミット変更がある。 - worktree を使わない: 数ファイル規模の変更。
- 並行数の上限は「担当ファイルが重複しないこと」で決める。同時に走る作業が同じファイルを編集する予定なら、worktree を増やしても解決しないので片方を待たせる。1 worktree = 1 ブランチ = 1 PR。運用手順は
docs/knowledge/parallel_work.mdに従う。
研究用変更
新しい Router、Retriever、Selector などを試す場合:
mainを最新化し、research/<method-name>ブランチを作る。- 実装する。既存の拡張ポイント(
ARCHITECTURE.mdの「拡張ポイント」)に差し込む形を優先し、Kernelの既定挙動は変えない。 - unit test を追加する。
- テストを実行する。
- commit SHA を取得する。
Object-Routing-Researchからその commit を使用して評価する。ベンチマーク結果にはbenchmarks/_provenance.pyが commit SHA を記録する。
実験で有効性を確認できるまでは、原則として main にマージしない。
main へ入れる条件
- 実験上の有効性または必要性が確認されている。
- unit test がある。
- 既存 API を不必要に壊さない(
docs/knowledge/contracts-and-compatibility.md)。 - 一般利用できる実装になっている。実行時依存を不必要に増やさない(増やす場合はユーザーの確認を取っている)。
- 必要なドキュメント(
CHANGELOG.md、該当する docs、ARCHITECTURE.md)が更新されている。
依存関係・互換性・凍結物
- 実行時依存は最小限に保つ(現在は
python-dotenvの 1 つ)。新しい実行時依存を追加する前に、必要性、標準ライブラリや既存の依存で代替したときのコスト、インストールサイズ・推移的依存・ライセンスへの影響をユーザーに示し、確認を取る。確認なしにpyproject.tomlのdependenciesを変更しない。ベンチマークや開発だけに要るものはbenchmark/devextra に置く。追加した場合は理由と影響を PR に書く(docs/decisions/0007-minimal-runtime-dependencies-with-user-approval.md)。 tests/fixtures/compat/v0.3.0/は互換性契約の凍結物である。書き換えず、新しい契約を凍結するときは新しいバージョンのディレクトリを追加する。benchmarks/results/*.jsonはコミットされた測定結果である。実装を変えずに数値だけを変更しない。再測定したら同じ PR で実装差分と一緒に更新し、benchmarks/README.mdの数値も揃える。- CI ワークフローの
concurrencyは同じ ref の実行中ジョブを打ち切る。mainに連続してマージすると中間コミットの CI が完了しないことがあるので、リリースタグを打つ前にmainの最新コミットの CI が緑であることを確認する。
セキュリティと設定
- 実行時に読まれる環境変数の一覧は
.env.exampleが正本である。python3 scripts/check_env_documentation.pyがコードの読み取りと記載の同期を検証する。環境変数を追加・削除したら同じ変更で.env.exampleも更新する。 - 必要な環境変数は LLM プロバイダーの API キー(
OPENAI_API_KEY、ANTHROPIC_API_KEY)、モデル設定(OPENAI_MODEL、ANTHROPIC_MODEL、ANTHROPIC_MAX_TOKENS、OPENAI_EMBEDDING_MODELなど)、通知 webhook(MARMO_NOTIFICATION_<DESTINATION>_URL)である。シークレットは環境変数または.envに保持し、git に含めない。 .envには秘密情報が入るため、その内容を読んだり、ログ・文書・報告へ転記したりしない。環境変数の一覧を確認するときは.env.exampleを読む。resources/skillsはサードパーティのコーパスで、再配布しない。git と sdist の両方から除外されている。- 権限、副作用分類、ポリシー評価、シークレット処理、HITL ゲートに触る変更は
docs/threat-model.mdに照らしてレビューし、信頼境界を動かしたら同文書を更新する。
最重要ルール
研究速度のために公開ライブラリの安定性を壊さない。一方で、研究用ブランチでは新しい手法を積極的に試してよい。