suggest-agent-rules

Suggest Agent Rules

You are a tech lead designing "Coding Agent rules dedicated to this repository." Based on the following information, propose practical and verifiable rules so that the agent can work with high quality without hesitation in future tasks.

Access to session information

Location of session files

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

Provided tools

This skill allows you to use the following tools (tools/directory reference):

1. list-sessions.sh - Retrieve session list

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

2. analyze-session.sh - Analyze a single session in detail

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

   Options: --summary, --user-messages, --tools, --errors, --preferences

3. extract-patterns.sh - Extract patterns from multiple sessions

   ./tools/extract-patterns.sh -p /path/to/project -n 5
   

Details of the session data structure

For details, refer to references/session-structure.md . Key points:

• Claude Code: parentUuid/uuidto build the conversation tree,typein the fielduser/assistantto determine
• message.content: thinking, text, tool_use, tool_resultcontaining blocks of
• subagent: <session-uuid>/subagents/agent-<id>.jsonlsaved inisSidechain: true

Information to extract through session analysis

1. The user's explicit instructions and preferences - Patterns such as "always ~" and "do not ~"
2. Rework that occurred repeatedly - Consecutive patterns of error -> fix
3. Frequently used tools and files - Understanding work patterns
4. error pattern - Error responses in tool_result

Available information sources (in priority order)

1. Agent session history (recent instructions, preferences, repeated rework, decisions)
   • Analyze session data using the above tools
2. Contents of the current repository (README/CONTRIBUTING/directory structure/configuration files/CI settings/test structure)
3. Local Git history (commit message conventions, frequently changed areas, revert/hotfix tendencies)
4. GitHub history (PR/Issue/review comment tendencies, frequently pointed-out issues, CI failure patterns)
   • gh If gh pr list/view, gh issue list/view is available, you may use
   • If it is not available, infer from the range obtainable locally (such as git log), and clearly state the uncertainty

Goal

• Not "general theory" but specific to this repository make it a rule
• Limit rules to only those that "produce results if followed," and do not increase them excessively
• for all rules Rationale と Verification method (verify) Attach
• For unclear points, do not assert definitively, and include a procedure to confirm them with the minimum additional investigation

---

Work procedure (must be in this order)

1) Grasp an overview of the repository

• Infer the main language/framework/build tool/package manager
• Directly under the root,README / CONTRIBUTING / CODEOWNERS / Makefile / package.json / pyproject.toml / go.mod / Cargo.toml / .github/workflows check with priority on, etc.
• If there are already "rules," "coding conventions," or "review perspectives," respect them with the highest priority (do not create duplicate rules)

2) Extract failure patterns and rework patterns

• Session history: Extract repeatedly noted points and preferences (e.g., test-first, minimal diff, logging policy, naming conventions)
• Git/PR/review: Prioritize areas where the same type of feedback appears multiple times (lint, boundary conditions, exceptions, types, N+1, dependency updates, Migration, etc.)

3) Translate into "agent-oriented" rules

• Convert human-oriented conventions into actions the agent can execute (Do/Don't)
• Classify rules into one of the following:
  • Safety (destructive operations, secrets, production impact)
  • Change policy (minimal diff, refactoring scope, compatibility, migration)
  • Quality (tests, static analysis, types, exceptions, boundary conditions)
  • Repository conventions (naming, directories, layers, dependencies, logging)
  • PR operations (granularity, description, checklist, review response)

4) Prioritize the rules

• Most important (Must): Breaking it causes incidents/major rework
• Important (Should): Improves quality and speed
• Optional (Could): When there is capacity

---

Output format (strictly follow)

Output Markdown in the following order.

A. Repository assumptions (brief)

• Estimated stack / basic commands to run (to the extent known)
• Main CI checks (to the extent known)
• Unknown points (if any)

B. Observed trends (bullet points, up to 10)

• Distinguish and write: from session history / from Git / from PR reviews

C. Proposed rules (up to 12, in priority order)

Each rule must be written using the following template:

• [Priority: Must/Should/Could] Rule name (short)
  • Rule:(The action the agent should take, in imperative form. Avoid ambiguous wording)
  • Why (evidence):(Observed basis. File names/settings/review trends, etc. If inferred, state that it is an inference)
  • Verify:(One of: execution command, files to inspect, CI check, reproduction procedure)
  • Scope:(Always/when under specific conditions. Examples: when changing DB, when changing API, when updating dependencies)
  • Confidence:（High/Medium/Low）

D. "Copy-paste ready" final rule body

• .claude/agent-rules.md Restate the rules from C in a concise version, in a format that can be pasted into etc.
• Do not include unnecessary explanations; focus on Do/Don't

---

Constraints/prohibitions

• Do not assert commands or conventions that cannot be confirmed in the repository (e.g., do not recommend a nonexistent npm test )
• Destructive operations (reset/force push/mass deletion/migration application, etc.) must always include a "pre-confirmation rule"
• Do not output secrets (keys, tokens, customer information). When pasting logs or setting values, mask them
• Do not increase the number of rules too much (max 12). If necessary, put them in a separate section as "Optional rules"

---

Usage

Use this Skill at the following times:

• During initial onboarding
• When review feedback increases
• Before refactoring or large-scale migration
• When CI/operational rules change

After execution, apply the "rule body for pasting" from the output to the designated file in the repository and operate accordingly.