エージェントと一緒に作業する

この手順でできること

この手順を終えると、Claude Code や Codex のようなコーディングエージェントが、FloatSoda の規約を読んで作業する準備が整います。エージェントに任せる範囲と、人間が確かめる箇所も決まります。手順は4つです。

エージェントが規約を読まないまま作業すると、ブランチ名、PR の範囲、日本語での出力といった決まりから外れた PR ができます。入口を先に教えておくと、差し戻しが減ります。このページの対象は「リポジトリでエージェントを使う」ことです。エージェント自体を作る手順は扱いません。

前提条件

• 手元でビルドとテストが通っていること

通っていなければ、先に 開発環境を用意するを済ませます。

手順1: エージェントの入口ファイルを確かめる

このリポジトリの共通指示は、リポジトリ直下の AGENTS.md にあります。Codex などの AGENTS.md を読むツールは、そのまま読みます。Claude Code は、CLAUDE.md の1行 @AGENTS.md を通して読みます。

プロジェクトの指示を足すときは、AGENTS.md に書きます。CLAUDE.md に書いた指示は、ほかのエージェントに届きません。

エージェントが AGENTS.md を読む状態で起動します。

できた? エージェントが読み込んだ指示の表示に、AGENTS.md が含まれている。表示のないツールでは、出力言語を尋ねて日本語と答えれば、補助の確認になる。

できなかったら

指示の表示に AGENTS.md がないとき、または日本語で答えないときは、エージェントが AGENTS.md を読めていない可能性があります。作業ディレクトリがリポジトリ直下か、CLAUDE.md が @AGENTS.md を含んでいるかを確かめます。

手順2: 規約の正本を確かめる

規約の正本は、開発規約の CONTRIBUTING.md と、レビューの基準の REVIEW.md です。AGENTS.md は規約を写さず、この2つを参照しています。人間が変更しても、エージェントが変更しても、規約は同じです。

エージェントに、作業の前に2つを読ませます。どの節を読むかは コントリビューターの規約にあります。

手順3: skill の位置を確かめる

リポジトリの skill の正本は .agents/skills/ です。.claude/skills/ は、Claude Code が .agents/skills/ を読めないために置いた派生のスタブです。frontmatter と正本へのポインタしか持たないので、直接編集しません。

どの skill が何に使えるかは、.agents/skills/ の各 SKILL.md の description に書かれています。実機テストの生成と実行、ジュニアコーダーテスト、リリース、OpenVR API の参照などがあります。一覧は .agents/skills/ のディレクトリで確かめます。

skill を足す・直す手順は、skill を足す・直すにあります。

手順4: 任せる範囲と、人間が確かめる箇所を決める

エージェントに任せてよい範囲は、作業の種類で3段階に分かれます。

段階	作業	進め方
任せない	Flutter にない API の実装	人間が実装し、DevEx(使い心地)と設計を確かめる
部分的に任せる	バグの修正	最初は調査だけを頼む。結果を読んでから、実装まで頼むかを決める
任せてよい	Flutter のウィジェットの移植	全面的に任せてよい。Flutter のテストも移植する

詳細は CONTRIBUTING.md の「コーディングエージェントに任せる範囲」にあります。

実機の確認は、エージェントではなく人間が判定します。エージェントは実機テストの運転と記録を担います。PR の本文のうち、エージェントが書いた箇所は、人間が内容を確かめます。

レビューは三層で行われます。自動(CodeRabbit)、人間・エージェントによる PR レビュー、フェーズ末の Codex による監査です。層の分担は、REVIEW.md の「9. レビューの層と分担」にあります。

C# の解析と変更には、Rider の MCP が使えるなら使います。使えなければ、dotnet CLI と検索で続けます。ソフトウェアをエージェントが勝手に入れることはありません。

できた? 「エージェントがやること」と「自分が確かめること」を、1行ずつ言える。

できなかったら

決められないときは、最初に任せる作業を調査に絞ります。調査の結果を読んでから、実装を依頼するかを決めます。

作業の進め方は コントリビューターの規約に、PR を出したあとの対応は レビューの指摘を受けて直すにあります。

うまくいかないとき

エージェントが規約から外れた変更をしたときは、症状ごとに規約で確かめて、エージェントにやり直させます。

症状	確かめる規約
ブランチ名に codex/、claude/、agent/ のようなツール名が入った	CONTRIBUTING.md の「ブランチ名」に従って切り直す
無関係な変更が混ざった	CONTRIBUTING.md の「PR のスコープ」に従って別の PR に分ける
.claude/skills/ を直接編集した	CONTRIBUTING.md の「エージェント向け skill を追加・変更する場合」に従って .agents/skills/ 側で直す

git push --force のように履歴を書き換える操作や、取り消せない操作は、実行する前に人間が確かめます。main へは直接 push せず、PR 経由にします(CONTRIBUTING.md の「ブランチ・PRフロー」)。