リポジトリのチェック

チェックを自動で作成する

ダッシュボードのはじめにでリポジトリのチェックを設定を選びます。HeyDeer がリポジトリと過去のプルリクエストを読み込み、チェックを追加するプルリクエストを作成します。クレジットは消費しません。

ご自身のコーディングエージェントに作成させる場合は、このプロンプトを渡してください。

Add HeyDeer repository checks to this repository following the guide below, and open a pull request with them. If it needs no new check, explain why instead.

# Write repository checks

A check is a Markdown file in `.agents/checks/` that states a requirement. Each check adds a reviewer of its own to every pull request that changes the files it covers, on top of a general review that already looks for common bugs and security issues. Add one only for a requirement that is specific to this codebase, costly to miss and easy to overlook.

1. Learn what the team cares about: the code, AGENTS.md or CLAUDE.md, REVIEW.md, the checks already in `.agents/checks/`, and as much of the merged pull requests and their review discussions as you need to see what reviewers keep asking for and where bugs were fixed.
2. Choose the requirements, usually one or two, leaving out what existing checks cover. Give each check one requirement or a few closely related ones, and keep one requirement in one check.
3. Write each check as `.agents/checks/<name>.md`, its name starting with a letter or digit and using only letters, digits, `.`, `_` and `-`, excluding every case variant of `README.md`:
   - Start with YAML frontmatter whose `files` lists glob patterns, relative to the repository root, for the files where the requirement can break. A pattern without a slash matches in any folder, a `!` prefix excludes, and the last matching pattern decides; exclusions need an including pattern. Compare the patterns with `git ls-files` so they match those files and little else. Add `skills` only to name repository skills the check needs.
     ```
     ---
     files:
       - "src/api/**/*.ts"
       - "!**/*.test.ts"
     ---
     ```
   - Below it, state the requirement as a condition on the code: what breaks it, what satisfies it and why it matters, with a short incorrect and correct example from this codebase. Most checks fit on a screen; a file can be up to 16000 bytes.
   - Write it in the language of the repository's own Markdown, such as its README and AGENTS.md, even when you write the pull request in another language.
4. In the pull request, say what each check covers and why it is worth a reviewer. Link the discussions that led to a check when there are any.

チェックを追加する

1. .agents/checks/ に、api-workspace-scope.md のような Markdown ファイルを作成します。
2. ファイルの先頭にフロントマターを書き、チェックの対象ファイルを files に列挙します。
3. フロントマターの下に要件を書きます。何が違反になり、何を満たせばよいか、そしてなぜ重要なのかを示します。
4. プルリクエストでコミットします。HeyDeer はチェックをプルリクエストから読み込むため、新しいチェックはそのプルリクエスト自体のレビューに適用されます。プルリクエストで変更できるものを参照してください。

.agents/checks/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)),
});
```

• フォルダー直下にあり、フロントマターに files がある .md ファイルが、それぞれチェックになります。README.md や他のレビューツール向けのチェックなど、フォルダー内のそれ以外のファイルは HeyDeer では無視されます。
• ファイル名は英字または数字で始め、英字、数字、.、_、- のみを使用します。

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

該当するチェックにはそれぞれ専用のレビュアーが付くため、チェックは徹底的ですが、より多くのクレジットを使います。チェックは見落とすと影響が大きく、見落としやすい要件に絞り、それ以外は REVIEW.md か AGENTS.md に書きます。

• コードベース固有のことを書きます。どのレビューでも一般的なバグやセキュリティの問題はすでに探しているため、「クエリは安全でなければならない」のようなチェックはコストが増えるだけで、見つかる問題は増えません。
• 1 つのチェックには 1 つの要件、または密接に関連するいくつかの要件だけを書きます。無関係な要件をまとめたチェックでは、それぞれの確認が浅くなります。
• 1 つの要件を複数のチェックに分けないでください。また、files は要件が破られうる場所に限定し、必要なところでだけチェックが実行されるようにします。
• 要件はコードに対する条件として書きます。何が要件に反し、何が満たすのか、そしてなぜ重要なのかを書くと、HeyDeer は想定外のケースも判断できます。コードベースから短い誤った例と正しい例を添えてください。
• 良いチェックのほとんどは 1 画面に収まります。複数のチェックで同じ背景知識が必要な場合は、スキルに移してください。
• 新しいチェックは、要件に違反するプルリクエストで試し、そのチェック名が付いた指摘事項が出ることを確認してください。

結果の表示

コードがチェックに違反すると、HeyDeer は GitHub と HeyDeer の両方で指摘事項を報告し、リポジトリのチェック: の後にそのチェックのファイル名を示します。指摘事項のないチェックは、レビューに何も追加しません。

これらの指摘事項は、他の指摘事項と同様にHeyDeer Review チェックと自動承認の判定に数えられます。HeyDeer Review チェックの要約には、失敗したリポジトリのチェックの数も示されます。

HeyDeer がチェックを完了できなかった場合、HeyDeer Review チェックには「レビューが完了していません」と表示されて失敗になります。もう一度レビューを依頼してください。

フロントマターのリファレンス

フロントマターは 2 つの --- 行で囲まれた YAML で、以下のキーを使用します。

他のレビューツールが読み取るキーなど、それ以外のキーは HeyDeer では無視されます。

除外パターンしかないなど、チェックが無効な場合、HeyDeer はそのチェックをスキップし、レビューの注意事項に記載します。レビューは実行されますが、HeyDeer は自動承認しません。

チェックの対象ファイル

変更されたファイルのうち 1 つ以上がチェックに一致するとチェックが適用され、HeyDeer はそれらのファイルに絞ってチェックを行います。

• すべての変更ファイルを対象にするには、files: ["**"] を使用します。
• パターンはリポジトリのルートからの相対パスで、*、**、{a,b} に対応しています。*.sql のようにスラッシュを含まないパターンは、どのフォルダーでも一致します。
• パターンは順番に適用され、ファイルに最後に一致したパターンで結果が決まります。そのため、後のパターンで、前の除外パターンが外したファイルを再び含めることができます。
• 自動生成ファイルが一致することはありません。

チェックが無視されているように見える場合は、トラブルシューティングを参照してください。

制限

ワークスペースは、すべてのリポジトリを合わせて、任意の 30 日間に最大 30 件のチェック生成タスクを開始できます。失敗またはキャンセルされたタスクも含まれます。

チェックファイルのサイズは最大 16,000 バイトです。

1 回のレビューで実行される該当チェックは、ファイル名順に最大 10 件です。残りのチェックは HeyDeer がレビューの注意事項に一覧表示し、HeyDeer Review チェックには「レビューが完了していません」と表示されます。そのレビューは自動承認されません。

該当するチェックが減るように、チェックを絞り込むか統合してください。先に実行するチェックを選ぶには、10-auth.md のようにファイル名の先頭に番号を付けます。

チェックが無効な場合

フロントマターまたは files キーがないファイルは無視されます。無効な YAML、サイズ上限を超えるフロントマター、空の files パターン、除外のみのパターンはスキップされ、報告されます。

変更されたファイルに一致するチェックについては、HeyDeer はファイル名、ファイルサイズ、スキル名も検証します。無効なチェックはスキップされ、レビューの注意事項に表示されます。レビューは続行されますが、HeyDeer は自動承認しません。

プルリクエストでチェックを修正してから、@heydeer review とコメントします。