Imported from 0x0c/unfydqry (docs/ja/AGENTS.md). Install upstream with npx skills add 0x0c/unfydqry --skill ja. Copyright stays with the author.

AGENTS.md — 並行開発のための共通作業合意（日本語版）

🌐 English version: ../../AGENTS.md

この文書は、同時にこのリポジトリで作業するすべての人（人間のコントリビューター と AI エージェントの両方）のための運用上の取り決めです。並行作業によって 衝突（同じファイルを取り合う変更）や 退行（他プラットフォームや CI ゲートを 静かに壊す変更）が起きないようにするために存在します。

何かに手を付ける前に読んでください。以下のルールは可能な限り自動化（git フック、 .claude/settings.json のフック、CODEOWNERS、CI）で強制されますが、自動化は合意を 裏で支えるだけで、合意そのものを置き換えるものではありません。

人間向けのセットアップ手順は CONTRIBUTING.md を参照してください。

1. すべての土台となる唯一のルール

検索ロジックはすべて単一の Rust コア（core/）に置く。 Swift と Kotlin の API は UniFFI が自動生成したバインディングであり、手書きコードではありません。したがって クロスプラットフォームの一致は構造的な性質であり、構成上成り立ちます — 3つの実装を 同期させ続けることを誰かが覚えているから成り立つのではありません。

この文書のすべてのルールはこの性質を守るためにあります。プラットフォームが分岐しうる 変更は、たとえコンパイルが通っても誤りです。

2. オーナーシップ・ゾーン

編集する前に、自分がどのゾーンにいるかを把握してください。ゾーンごとにルールが 異なります。

⛔ 生成バインディング の2ファイルは .claude/settings.json の PreToolUse フックで 書き込み保護されています — エージェントによる Edit/Write はブロックされます。 これらの API を変えるには core/ を編集して make gen-bindings を実行してください。

3. 衝突を避ける（並行作業）

1. 1タスク = 1ブランチ。 独立した2つのタスクでブランチを共有しない。
2. ゾーンを宣言する。 着手前に、どのオーナーシップ・ゾーンとどのトップレベル ディレクトリを触るかを（PR 説明・タスクメモ・コミットで）述べる。別の進行中タスクが 既にそのゾーンを所有していれば、先に調整する。
3. 自分のレーンに留まる。 単一ゾーンに収まる変更を優先する。core/ と プラットフォーム層にまたがる変更は普通（例: 新しい FFI メソッドとそのホスト利用） ですが、1タスクで多数のプラットフォームに編集を広げると衝突面が増える — 分割できる なら分割する。
4. 溜め込まず rebase する。 ブランチを main に追従させ、マージを小さく保つ。 共有ファイルに対する長命ブランチが衝突の主因。
5. 生成ファイルを手で解決しない。 バインディングファイルがコンフリクトしても 手でマージしない。マージ済みの core/ の上で make gen-bindings を再実行し、 再生成された出力をコミットする。

4. 退行を避ける（push する前に）

CI が回すのと同じゲートを、push 前にローカルで回す:

make ci          # = make check  +  make verify-bindings

• make check → cargo fmt --check、cargo clippy -D warnings、cargo test
• make verify-bindings → コミット済みの Swift/Kotlin バインディングが、現在の core/ から生成されるものと食い違えば失敗する（＝ドリフトや再生成漏れを検出）。

FFI に露出する Rust シグネチャ（UniFFI 経由で公開されるもの）を変更した場合は、 必ず:

make gen-bindings   # Swift + Kotlin バインディングをその場で再生成
git add ios/Sources/UnifiedQuery/UnifiedQuery.swift \
        android/sample/unifiedquery/src/main/kotlin/uniffi/unfydqry/unfydqry.kt

…として、再生成されたバインディングを Rust シグネチャ変更と同じ変更でコミットする。 シグネチャだけ変えて再生成バインディングを伴わないコミットは、退行の予備軍です。

5. これを支える自動化

上記をすべて覚えておく必要はありません — 重要な部分はリポジトリが強制します。 クローンごとに一度だけ git フックを有効化してください:

make setup     # = git config core.hooksPath .githooks

core.hooksPath はローカルの git 設定であり、clone や pull では引き継がれ ません。そのためクローンごとに一度有効化が必要です（フックが存在する前にクローン した人は、有効化するまで対象外）。安全網として、日常のターゲット（make check / make ci / make gen-bindings）は先頭で ensure-hooks を実行する自己修復を行うため、 通常のワークフローを次に使った時点でフックが自動的に設定されます。

6. クイックチェックリスト

• このタスク専用のブランチにいる。
• 挙動の変更は core/ で行い、プラットフォームごとに複製していない。
• 生成バインディングファイルを手編集していない。
• FFI シグネチャを変えたら: make gen-bindings を実行し結果をコミットした。
• ドキュメントを変えたら英語版と日本語版を一緒に更新した。
• make ci がローカルで通る。
• ブランチを最新の main に rebase した。