suggest-agent-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Suggest Agent Rules

あなたは「このリポジトリ専用のCoding Agentルール」を設計するテックリードです。以下の情報を根拠に、エージェントが将来の作業で迷わず高品質に動けるよう、実務的で検証可能なルールを提案してください。

You are a tech lead tasked with designing "Coding Agent Rules exclusive to this repository." Based on the following information, please propose practical, verifiable rules that will enable the agent to work consistently and with high quality in future tasks.

セッション情報へのアクセス

Accessing Session Information

セッションファイルの場所

Session File Locations

Agent	Path	File Format
Claude Code	`~/.claude/projects/<project-path-encoded>/`	`<UUID>.jsonl`
Codex CLI	`~/.codex/sessions/YYYY/MM/DD/`	`rollout-<datetime>-<UUID>.jsonl`

プロジェクトパスのエンコード:

/Users/username/projects/myapp

→

-Users-username-projects-myapp

Agent	Path	File Format
Claude Code	`~/.claude/projects/<project-path-encoded>/`	`<UUID>.jsonl`
Codex CLI	`~/.codex/sessions/YYYY/MM/DD/`	`rollout-<datetime>-<UUID>.jsonl`

Project Path Encoding:

/Users/username/projects/myapp

→

-Users-username-projects-myapp

提供ツール

Available Tools

このスキルでは以下のツールを利用できます（

tools/

ディレクトリ参照）:

list-sessions.sh - セッション一覧を取得

bash

./tools/list-sessions.sh -p /path/to/project -n 10

analyze-session.sh - 単一セッションを詳細分析

bash

./tools/analyze-session.sh <session-file> --all

オプション:

--summary

--user-messages

--tools

--errors

--preferences

extract-patterns.sh - 複数セッションからパターンを抽出
bash
```
./tools/extract-patterns.sh -p /path/to/project -n 5
```

The following tools are available for this skill (see the

tools/

directory):

list-sessions.sh - Retrieve session list

bash

./tools/list-sessions.sh -p /path/to/project -n 10

analyze-session.sh - Detailed analysis of a single session

bash

./tools/analyze-session.sh <session-file> --all

Options:

--summary

--user-messages

--tools

--errors

--preferences

extract-patterns.sh - Extract patterns from multiple sessions
bash
```
./tools/extract-patterns.sh -p /path/to/project -n 5
```

セッションデータ構造の詳細

Details of Session Data Structure

詳細は

references/session-structure.md

を参照。主要なポイント:

Claude Code:
```
parentUuid
```
/
```
uuid
```
で会話ツリーを構築、
```
type
```
フィールドで
```
user
```
/
```
assistant
```
を判別
message.content:
```
thinking
```
,
```
text
```
,
```
tool_use
```
,
```
tool_result
```
のブロックを含む

サブエージェント:

<session-uuid>/subagents/agent-<id>.jsonl

に保存、

isSidechain: true

For details, refer to

references/session-structure.md

. Key points:

Claude Code: Build conversation trees using
```
parentUuid
```
/
```
uuid
```
, distinguish between
```
user
```
/
```
assistant
```
via the
```
type
```
field
message.content: Contains blocks for
```
thinking
```
,
```
text
```
,
```
tool_use
```
,
```
tool_result
```

Subagents: Stored in

<session-uuid>/subagents/agent-<id>.jsonl

, marked with

isSidechain: true

セッション解析で抽出すべき情報

Information to Extract in Session Analysis

ユーザーの明示的な指示・好み - 「必ず〜」「〜しないで」などのパターン
繰り返し発生した手戻り - エラー→修正の連続パターン
よく使用されるツールとファイル - 作業パターンの把握
エラーパターン - tool_resultでのエラー応答

Explicit user instructions/preferences - Patterns like "always..." or "do not..."
Recurring rework cycles - Sequential patterns of error → correction
Frequently used tools and files - Understand work patterns
Error patterns - Error responses in
```
tool_result
```

利用できる情報源（優先順）

Available Information Sources (Priority Order)

Agentのセッション履歴（直近の指示・好み・繰り返し発生した手戻り・決定事項）
- 上記ツールを使用してセッションデータを分析
現在のリポジトリの内容（README/CONTRIBUTING/ディレクトリ構造/設定ファイル/CI設定/テスト構成）
ローカルGit履歴（コミットメッセージ規約・変更頻度の高い領域・リバート/ホットフィックス傾向）
GitHub履歴（PR/Issue/レビューコメントの傾向、指摘が多い論点、CI落ちパターン）
- ```
gh
```
  が使えるなら
```
gh pr list/view
```
  ,
```
gh issue list/view
```
  等を用いて良い
- 使えない場合はローカルで取れる範囲（git log等）で推定し、不確実性を明示する

Agent session history (recent instructions, preferences, recurring rework, decisions)
- Analyze session data using the tools above
Current repository content (README/CONTRIBUTING, directory structure, configuration files, CI settings, test configurations)
Local Git history (commit message conventions, frequently modified areas, revert/hotfix trends)
GitHub history (PR/Issue/review comment trends, commonly raised issues, CI failure patterns)
- If
```
gh
```
  is available, use commands like
```
gh pr list/view
```
  ,
```
gh issue list/view
```
  , etc.
- If not, estimate using locally available data (e.g., git log) and explicitly state any uncertainties

ゴール

Goals

“一般論”ではなく このリポジトリ固有の ルールにする
ルールは「守れば成果が上がる」ものだけに絞り、過剰に増やさない
すべてのルールに根拠と 確認方法（verify） を付ける
不明点は断定せず、最小の追加調査で確かめる手順を添える

Create rules specific to this repository, not general guidelines
Only include rules that directly improve outcomes when followed; avoid overloading
Attach evidence and a verification method to every rule
Do not make definitive statements about unclear points; instead, include steps to verify with minimal additional research

作業手順（必ずこの順で）

Workflow Steps (Follow Strictly in This Order)

1) リポジトリ概観の把握

1) Understand Repository Overview

主要言語/フレームワーク/ビルドツール/パッケージマネージャを推定

ルート直下、

README

CONTRIBUTING

CODEOWNERS

Makefile

package.json

pyproject.toml

go.mod

Cargo.toml

.github/workflows

等を優先して確認

既に「ルール」「コーディング規約」「レビュー観点」があるならそれを最優先で尊重（重複ルールは作らない）

Estimate the primary language/framework, build tools, and package managers

Prioritize checking root directory files like

README

CONTRIBUTING

CODEOWNERS

Makefile

package.json

pyproject.toml

go.mod

Cargo.toml

.github/workflows

If existing "rules", "coding conventions", or "review guidelines" exist, respect them as top priority (do not create duplicate rules)

2) 失敗パターン・手戻りパターンの抽出

2) Extract Failure Patterns & Rework Cycles

セッション履歴：繰り返し注意された点、好み（例：テスト先行、差分最小、ログ方針、命名規約）を抽出
Git/PR/レビュー：同じ種類の指摘が複数回出る領域を優先（lint、境界条件、例外、型、N+1、依存更新、Migration等）

Session history: Extract repeatedly emphasized points and preferences (e.g., test-first approach, minimal diffs, logging policies, naming conventions)
Git/PR/reviews: Prioritize areas where the same type of feedback is raised multiple times (linting, boundary conditions, exceptions, types, N+1 queries, dependency updates, migrations, etc.)

3) “エージェント向け”に翻訳してルール化

3) Translate to "Agent-Friendly" Rules

人間向け規約を、エージェントが実行できる行動（Do/Don’t）へ落とす
ルールは次のいずれかに分類する：
- 安全（破壊的操作・秘密情報・本番影響）
- 変更方針（差分最小、リファクタ範囲、互換性、移行）
- 品質（テスト、静的解析、型、例外、境界条件）
- リポジトリ慣習（命名、ディレクトリ、レイヤー、依存、ログ）
- PR運用（粒度、説明、チェックリスト、レビュー対応）

Convert human-oriented conventions into actionable Do/Don’t behaviors that the agent can execute
Categorize rules into one of the following:
- Safety (destructive operations, sensitive information, production impact)
- Change Policies (minimal diffs, refactoring scope, compatibility, migrations)
- Quality (testing, static analysis, types, exceptions, boundary conditions)
- Repository Conventions (naming, directories, layers, dependencies, logging)
- PR Operations (granularity, descriptions, checklists, review responses)

4) ルールの優先度付け

4) Prioritize Rules

最重要（Must）: 破ると事故/大幅手戻りになる
重要（Should）: 品質や速度に効く
任意（Could）: 余裕がある時に

Highest Priority (Must): Violations lead to incidents or significant rework
Important (Should): Improves quality or speed
Optional (Could): For when time allows

出力フォーマット（厳守）

Output Format (Strictly Adhere To)

以下の順番でMarkdownを出力してください。

Output Markdown in the following order:

A. リポジトリの前提（短く）

A. Repository Premises (Brief)

推定スタック / 実行すべき基本コマンド（分かる範囲）
CIの主要チェック（分かる範囲）
不明点（あれば）

Estimated stack / basic commands to run (as much as is known)
Key CI checks (as much as is known)
Uncertainties (if any)

B. 観測された傾向（箇条書き・最大10個）

B. Observed Trends (Bullet Points, Max 10)

セッション履歴由来 / Git由来 / PRレビュー由来を区別して書く

Distinguish between sources: from session history / from Git / from PR reviews

C. 提案ルール（最大12個、優先度順）

C. Proposed Rules (Max 12, Ordered by Priority)

各ルールは必ず次のテンプレで書く：

[Priority: Must/Should/Could] ルール名（短く）
- Rule:（エージェントが取るべき行動を命令形で。曖昧語を避ける）
- Why (evidence):（観測された根拠。ファイル名/設定/レビュー傾向など。推測なら推測と明記）
- Verify:（実行コマンド、見るべきファイル、CIで確認、再現手順のいずれか）
- Scope:（常に/特定条件のとき。例：DB変更時、API変更時、依存更新時）
- Confidence:（High/Medium/Low）

Each rule must follow this template:

[Priority: Must/Should/Could] Rule Name (Short)
- Rule: (Imperative action the agent should take. Avoid ambiguous language.)
- Why (evidence): (Observed evidence, such as filenames, configurations, review trends. Explicitly note if it’s an assumption.)
- Verify: (One of: execution command, files to check, CI verification steps, reproduction procedure)
- Scope: (Always / Under specific conditions, e.g., during DB changes, API changes, dependency updates)
- Confidence: (High/Medium/Low)

D. “貼り付け用”の最終ルール本文

D. "Copy-Paste Ready" Final Rule Text

```
.claude/agent-rules.md
```
等に貼れる体裁で、Cのルールを簡潔版に再掲する
余計な解説は入れず、Do/Don’t中心にする

Reproduce the rules from Section C in a concise format suitable for pasting into files like
```
.claude/agent-rules.md
```
Focus on Do/Don’t statements; omit extra explanations

制約・禁止事項

Constraints & Prohibitions

リポジトリで確認できないコマンドや規約を断定しない（例：存在しない
```
npm test
```
を推奨しない）
破壊的操作（reset/force push/大量削除/マイグレーション適用等）は “事前確認ルール” を必ず含める
秘密情報（鍵、トークン、顧客情報）を出力しない。ログや設定値を貼る場合はマスキングする
ルール数は増やしすぎない（最大12）。必要なら「次点ルール（Optional）」として別枠にする

Do not assert commands or conventions that cannot be verified in the repository (e.g., do not recommend
```
npm test
```
if it doesn’t exist)
For destructive operations (reset/force push, mass deletion, migration application, etc.), always include a "pre-confirmation rule"
Do not output sensitive information (keys, tokens, customer data). Mask logs or configuration values when pasting them
Do not create too many rules (max 12). If necessary, place lower-priority rules in a separate "Optional Rules" section

Usage

このSkillは次のタイミングで使う：

初回オンボーディング時
レビュー指摘が増えたとき
リファクタや大規模移行の前
CI/運用ルールが変わったとき

実行後、出力の「貼り付け用ルール本文」をリポジトリの所定ファイルに反映して運用する。

Use this Skill at the following times:

During initial onboarding
When review feedback increases
Before refactoring or large-scale migrations
When CI/operation rules change

After execution, reflect the "copy-paste ready rule text" from the output into the designated repository file for ongoing use.