Suggest Agent Rules

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`

Project Path Encoding:

/Users/username/projects/myapp

→

-Users-username-projects-myapp

Available Tools

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

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

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 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

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) Understand Repository Overview

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) Extract Failure Patterns & Rework Cycles

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) Translate to "Agent-Friendly" Rules

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) Prioritize Rules

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)

Output Markdown in the following order:

A. Repository Premises (Brief)

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

B. Observed Trends (Bullet Points, Max 10)

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

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

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. "Copy-Paste Ready" Final Rule Text

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

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

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.

suggest-agent-rules

NPX Install

Tags

SKILL.md Content (Chinese)