ベストプラクティス

効果的なチェックの書き方

良いチェックは、新しいチームメイトがコードを読んで適用できるルールのように書かれています。ファイル形式とオプションについては、リポジトリのチェックを参照してください。

1 つのチェックに判定可能なルールを 1 つ

関連のないルールは、それぞれ別のファイルに書いてください。指摘事項にはチェックのファイル名がラベルとして付き、各ファイルに独自のパターンを設定できます。

ルールは、コードに対する条件として書きます。何が違反になり、何を満たせばよいかを示してください。

ファイルパターンで対象を絞る

files パターンを追加して、ルールが重要な場所にだけチェックが適用されるようにします。パターンがないと、すべてのプルリクエストに適用されます。テストやフィクスチャは ! で除外し、YAML ではすべてのパターンを引用符で囲んでください。

理由と例を示す

ルールが重要な理由を書くと、HeyDeer は想定外のケースでも判断できます。ルールに違反するコードだけでなく正しいコードも説明し、コードベースから短い誤った例と正しい例を示してください。

チェックを短く保ち、順序を整える

良いチェックのほとんどは 1 画面に収まります。複数のチェックで同じ背景知識が必要な場合は、スキルに移してください。

各レビューで適用される該当チェックはファイル名順に最大 10 個なので、最も重要なチェックには 10-auth.md のように数字の接頭辞を付けてください。単純なチェックには skip_extra_reviewers: true を設定すると、詳細レビューでも標準と同じようにレビューされます。1 回のレビューにつき最大 10 個のチェックを参照してください。

実際のプルリクエストでテストする

チェックをマージします。HeyDeer はチェックをベースブランチから読み込みます。
ルールに違反するプルリクエストを作成し、そのチェックの名前が付いた指摘事項が表示されることを確認します。ルールに従ったコードには指摘事項が表示されないことも確認してください。
チェックが正しいコードを指摘する場合は、ルールまたはパターンを厳密にします。見逃すケースがある場合は、そのケースを誤った例として追加します。

アンチパターン

アンチパターン	うまくいかない理由	代わりに書く内容
あいまい：「API 設計のベストプラクティスに従う。」	コードを照らし合わせる条件がないため、指摘事項がばらつきます。	「src/api/ 配下のハンドラーは、ルートのスキーマでリクエストボディを検証する。」
HeyDeer から見えない：「CI が成功し、セキュリティの承認が得られない限り失敗にする。」	HeyDeer は CI の結果や承認を見ることができません。	必須の CI と承認には、GitHub のブランチルールを使います。
何かを実行させる：「テストを実行して結果を報告する。」	HeyDeer はコード、テスト、ビルドを実行しません。	「src/billing/ の変更には、変更された関数を実行するテストを含める。」
フォーマット：「インデントはスペース 2 つにし、インポートを並べ替える。」	フォーマッターやリンターなら、これを正確に強制できます。	それらのツールを CI で実行します。
推測：「遅くなりそうな箇所を指摘する。」	具体的なパターンがないと、指摘事項は意見になってしまいます。	「ループ内で項目ごとにデータベースクエリを発行してはならない。代わりにクエリをまとめる。」
1 つのファイルに複数のルール：「認証、ログ、命名、テストをチェックする。」	指摘事項が 1 つのラベルを共有し、ルールごとに対象を絞ることができません。	ルールごとに 1 ファイルとし、それぞれに独自のパターンを設定します。

書き換え前と書き換え後

書き換え前：

---
files: "src/**"
---
Follow API best practices. Make sure endpoints are secure, fast,
and well tested, and that naming is consistent. Run the test suite
and fail if anything breaks.

書き換え後（.agents/checks/20-api-workspace-scope.md）：

---
files:
  - "src/api/**/*.ts"
  - "!**/*.test.ts"
---
# API handlers scope queries to the caller’s workspace

Every query in an API handler that reads or writes a table with a
`workspace_id` column must filter on the workspace returned by
`requireWorkspace()`. Without that filter, one customer can read
or change another customer’s data.

Fail when a handler queries such a table without that filter.
Pass when every such query filters on the workspace, or when the
handler only touches tables without a `workspace_id` column.

Incorrect:

```ts
const invoice = await db.query.invoices.findFirst({
  where: eq(invoices.id, id),
});
```

Correct:

```ts
const { workspaceId } = await requireWorkspace(req);
const invoice = await db.query.invoices.findFirst({
  where: and(eq(invoices.id, id), eq(invoices.workspaceId, workspaceId)),
});
```

書き換え後は、関心事を 1 つに絞り、対象を API ハンドラーに限定し、何が失敗で何が合格かを示し、リスクを説明しています。その他の関心事は、それぞれ独自のチェックにするか、ツールや AGENTS.md に移します。