agent-md-advisor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Markdown Advisor

帮助用户回答、审查、优化和创建 AI coding agent 指令文件，重点覆盖

AGENTS.md

与

CLAUDE.md

。

Helps users answer, review, optimize, and create AI coding agent instruction files, with a focus on

AGENTS.md

and

CLAUDE.md

设计模式

Design Patterns

本 skill 主要采用：

Advisor：回答格式、结构、放什么/不放什么等最佳实践问题
Reviewer：诊断已有
```
AGENTS.md
```
/
```
CLAUDE.md
```
是否违反最佳实践
Generator：根据项目和用户描述创建新的指令文件
Editor：用户明确要求执行优化时，直接修改相关文件

This skill mainly adopts:

Advisor: Answers best practice questions about format, structure, what to include/exclude, etc.
Reviewer: Diagnoses whether existing
```
AGENTS.md
```
/
```
CLAUDE.md
```
violate best practices
Generator: Creates new instruction files based on projects and user descriptions
Editor: Directly modifies relevant files when users explicitly request optimization

Gotchas

不要把
```
AGENTS.md
```
/
```
CLAUDE.md
```
写成项目百科、README 复制品或完整 API 文档
不要把
```
AGENTS.md
```
/
```
CLAUDE.md
```
写成人设说明书、口号墙或愿望清单；它应该像给资深工程师的技术简报
不要把 linter、formatter、类型检查器能确定执行的规则改写成大量自然语言
不要写实际密钥、token、生产连接串、客户数据或内部安全细节；只写密钥位置和访问方式
不要凭空发明命令；先看
```
package.json
```
、
```
pyproject.toml
```
、
```
Makefile
```
、CI workflow、README 等可验证来源
不要默认建议复杂
```
.claude/agents
```
、hooks、MCP、skills；先判断项目是否真的需要
如果用户只要求诊断，不要直接改文件；如果用户说“优化、重写、创建、执行”，可以落地修改
保持文件短而可执行：
```
AGENTS.md
```
理想上 150 行以内，
```
CLAUDE.md
```
优先压到 80-120 行，超过 200 行要强烈考虑拆分

Don't write
```
AGENTS.md
```
/
```
CLAUDE.md
```
as project encyclopedias, README duplicates, or complete API documentation
Don't write
```
AGENTS.md
```
/
```
CLAUDE.md
```
as persona manuals, slogan walls, or wish lists; it should read like a technical briefing for senior engineers
Don't rewrite rules that can be enforced by linters, formatters, or type checkers into large amounts of natural language
Don't write actual secrets, tokens, production connection strings, customer data, or internal security details; only write the location of secrets and access methods
Don't invent commands out of thin air; first check verifiable sources like
```
package.json
```
,
```
pyproject.toml
```
,
```
Makefile
```
, CI workflows, README, etc.
Don't default to suggesting complex
```
.claude/agents
```
, hooks, MCP, skills; first determine if the project actually needs them
If users only request diagnosis, don't directly modify files; if users say "optimize, rewrite, create, execute", you can implement modifications
Keep files short and actionable:
```
AGENTS.md
```
should ideally be within 150 lines,
```
CLAUDE.md
```
should be prioritized to 80-120 lines, and strongly consider splitting if it exceeds 200 lines

工作模式

Working Modes

先判断用户需求属于哪一类：

问答模式：解释格式、章节、层级、AGENTS.md 和 CLAUDE.md 区别、最佳实践。
诊断模式：用户已有文件，希望指出问题、违反的实践和改进建议。
优化模式：用户明确要求修改、重写、压缩、整理或“执行优化”。
创建模式：用户还没有文件，或希望根据描述生成
```
AGENTS.md
```
/
```
CLAUDE.md
```
。

First determine which category the user's request falls into:

Q&A Mode: Explains format, sections, hierarchy, differences between AGENTS.md and CLAUDE.md, and best practices.
Diagnosis Mode: Users have existing files and want to identify issues, violated practices, and improvement suggestions.
Optimization Mode: Users explicitly request modification, rewriting, compression, organization, or "execute optimization".
Creation Mode: Users don't have files yet, or want to generate
```
AGENTS.md
```
/
```
CLAUDE.md
```
based on descriptions.

使用流程

Usage Flow

复制此清单并跟踪进度：

text

处理进度：
- [ ] 步骤 1：识别模式和目标文件
- [ ] 步骤 2：读取必要参考资料
- [ ] 步骤 3：读取项目上下文或用户提供内容
- [ ] 步骤 4：给出诊断、方案或草稿
- [ ] 步骤 5：如用户要求落地，修改文件并验证

Copy this checklist and track progress:

text

Processing Progress:
- [ ] Step 1: Identify mode and target files
- [ ] Step 2: Read necessary reference materials
- [ ] Step 3: Read project context or user-provided content
- [ ] Step 4: Provide diagnosis, solution, or draft
- [ ] Step 5: If user requests implementation, modify files and verify

Step 1: 识别模式和目标文件

Step 1: Identify Mode and Target Files

优先判断目标：

跨工具、Codex、Copilot、Cursor、通用 AI coding agent：优先
```
AGENTS.md
```
Claude Code 项目记忆、Claude 专属规则：优先
```
CLAUDE.md
```
每个项目都会重复的工作偏好：优先放 global/user 级配置
当前项目、技术栈、架构和命令：优先放 repo 内
```
AGENTS.md
```
/
```
CLAUDE.md
```
个人本地偏好：优先
```
CLAUDE.local.md
```
或用户级 memory，不要提交到团队共享文件
Monorepo 或多技术栈：考虑根目录文件 + 子目录嵌套文件

如果用户没有指定文件名：

想要通用标准：建议
```
AGENTS.md
```
主要使用 Claude Code：建议
```
CLAUDE.md
```
同时使用多种工具：建议以
```
AGENTS.md
```
为主，并视工具支持情况用
```
CLAUDE.md
```
或符号链接兼容

Prioritize judging the target:

Cross-tool, Codex, Copilot, Cursor, general AI coding agents: Prioritize
```
AGENTS.md
```
Claude Code project memory, Claude-specific rules: Prioritize
```
CLAUDE.md
```
Work preferences repeated across projects: Prioritize placing in global/user-level configurations
Current project, tech stack, architecture, and commands: Prioritize placing in repo-level
```
AGENTS.md
```
/
```
CLAUDE.md
```
Personal local preferences: Prioritize
```
CLAUDE.local.md
```
or user-level memory, do not submit to team-shared files
Monorepo or multi-tech stack: Consider root directory files + subdirectory nested files

If users don't specify a file name:

Want general standards: Recommend
```
AGENTS.md
```
Mainly use Claude Code: Recommend
```
CLAUDE.md
```
Use multiple tools simultaneously: Recommend focusing on
```
AGENTS.md
```
, and use
```
CLAUDE.md
```
or symbolic links for compatibility depending on tool support

Step 2: 读取必要参考

Step 2: Read Necessary References

回答最佳实践问题：读 references/best-practices.md
审查或评分已有文件：读 references/review-rubric.md
创建或重写文件：读 references/templates.md
需要追溯资料依据时：读 references/source-notes.md

Answering best practice questions: Read references/best-practices.md
Reviewing or scoring existing files: Read references/review-rubric.md
Creating or rewriting files: Read references/templates.md
When needing to trace source basis: Read references/source-notes.md

Step 3: 读取项目上下文

Step 3: Read Project Context

诊断或创建文件前，先读取最小必要上下文：

目标文件：
```
AGENTS.md
```
、
```
CLAUDE.md
```
、
```
CLAUDE.local.md
```
项目概览：
```
README.md
```

技术栈和命令：

package.json

、

pyproject.toml

、

Makefile

、

justfile

、

Taskfile.yml

、

pnpm-workspace.yaml

测试和 CI：

.github/workflows/

、

pytest.ini

、

vitest.config.*

、

tsconfig.json

现有 AI 配置：

.claude/

、

.cursor/rules/

、

.github/copilot-instructions.md

只读与判断有关的文件。不要为了写指令文件而扫描整个仓库。

Before diagnosing or creating files, first read the minimum necessary context:

Target files:
```
AGENTS.md
```
,
```
CLAUDE.md
```
,
```
CLAUDE.local.md
```
Project overview:
```
README.md
```

Tech stack and commands:

package.json

pyproject.toml

Makefile

justfile

Taskfile.yml

pnpm-workspace.yaml

Testing and CI:

.github/workflows/

pytest.ini

vitest.config.*

tsconfig.json

Existing AI configurations:

.claude/

.cursor/rules/

.github/copilot-instructions.md

Only read files relevant to the judgment. Don't scan the entire repository just to write instruction files.

Step 4: 输出方式

Step 4: Output Methods

问答模式

Q&A Mode

用简洁中文回答，并给出可操作判断：

markdown

结论：...

推荐结构：
- ...

注意事项：
- ...

Answer in concise English and provide actionable judgments:

markdown

Conclusion: ...

Recommended Structure:
- ...

Notes:
- ...

诊断模式

Diagnosis Mode

必须明确给结论和优先级：

markdown

undefined

Must clearly provide conclusions and priorities:

markdown

undefined

Agent 指令文件诊断

Agent Instruction File Diagnosis

结论：优秀 / 基本可用 / 需要重构 / 风险较高成熟度：L0-L6 中的某一级

Conclusion: Excellent / Basically Usable / Needs Refactoring / High Risk Maturity Level: One level from L0-L6

主要问题

Key Issues

[P1] ...
[P2] ...

[P1] ...
[P2] ...

做得好的地方

Strengths

优化建议

Optimization Suggestions

建议改法

Recommended Changes

保留：...
删除：...
拆分：...
新增：...


如果能定位具体行，引用文件路径和行号。问题要围绕“会不会让 agent 更可靠”判断，不要只做文字润色。

Keep: ...
Remove: ...
Split: ...
Add: ...


If specific lines can be located, reference the file path and line numbers. Issues should be judged based on "Will removing this line make the agent more likely to make mistakes?", not just text polishing.

优化模式

Optimization Mode

先快速诊断，再直接编辑。编辑原则：

保留真实、稳定、全局适用的信息
删除空泛、重复、过期、过细、容易从代码推断的信息
把长 SOP、API 文档、风格指南改成“Read when”引用
把命令改成可复制的真实命令
把硬规则压缩成能阻止具体错误的清单，
```
MUST
```
/
```
MUST NOT
```
只留给少数关键约束
把安全边界和高风险操作写清楚

完成后说明改了什么，并建议用户实际跑一次常见任务来验证。

First perform a quick diagnosis, then directly edit. Editing principles:

Retain real, stable, globally applicable information
Remove vague, repetitive, outdated, overly detailed, or easily inferable information from code
Rewrite long SOPs, API documentation, and style guides into "Read when" references
Replace commands with copyable real commands
Compress hard rules into checklists that can prevent specific errors; reserve
```
MUST
```
/
```
MUST NOT
```
only for a few key constraints
Clearly write security boundaries and high-risk operations

After completion, explain what was changed and suggest users run common tasks to verify.

创建模式

Creation Mode

根据用户描述和项目上下文生成文件。信息不足时先创建保守的最小可用版本，不要臆造复杂规则。

创建时优先包含：

项目一句话上下文
技术栈
常用命令
架构地图 / 代码放置规则
硬规则和非默认约定
测试和完成标准
安全和权限边界
参考文档及 Read when 触发条件

Generate files based on user descriptions and project context. If information is insufficient, first create a conservative minimal viable version, don't invent complex rules.

Prioritize including the following when creating:

One-sentence project context
Tech stack
Common commands
Architecture map / code placement rules
Hard rules and non-default conventions
Testing and completion standards
Security and permission boundaries
Reference documents and "Read when" trigger conditions

审查原则

Review Principles

每一行都要回答：“删掉这行，agent 会更容易犯错吗？”
写项目特有的、非显然的、可执行的规则
用精确命令替代“运行测试”“正常构建”等模糊说法
用文件路径和好/坏示例指向真实代码模式
用渐进披露承载长内容：根文件只做路由和关键约束
把 Global / Project / Local 三层分开，避免把个人习惯和项目事实混在同一个共享文件里
在 agent 反复犯同一种错误后再补规则，避免一开始写成巨型说明书
把确定性检查交给工具，把策略、边界和例外写给 agent
Treat instruction files as code：随项目变化审查、修剪和提交

For every line, ask: "If I delete this line, will the agent be more likely to make mistakes?"
Write project-specific, non-obvious, actionable rules
Replace vague statements like "run tests" "build normally" with precise commands
Point to real code patterns using file paths and good/bad examples
Use progressive disclosure for long content: Root files only handle routing and key constraints
Separate Global / Project / Local layers, avoid mixing personal habits and project facts in the same shared file
Only add rules after the agent repeatedly makes the same mistake, avoid writing a giant manual at the start
Leave deterministic checks to tools, write strategies, boundaries, and exceptions for agents
Treat instruction files as code: Review, prune, and commit as the project changes