agentic-rules-writer

Agentic Rules Writer

为任意 AI 编码 Agent 生成量身定制的规则或指令文件。该技能会运行交互式问卷，获取 using-ecosystem 元技能提供的已安装技能和 Agent 清单，并按所选 Agent 和作用范围要求的格式与位置写入输出。

适用场景

• 首次设置新的 AI 编码 Agent
• 创建团队共享的项目规则，让开发者获得一致的行为
• 在项目中添加个人开发专属规则（由 git 忽略）
• 安装新技能后，更新规则文件并添加技能引用

快速开始

/agentic-rules-writer claude
/agentic-rules-writer cursor
/agentic-rules-writer codex
/agentic-rules-writer              # asks which agent

---

阶段 1：选择 Agent

如果提供了 $ARGUMENTS，请根据下表将其匹配到相应的 Agent（不区分大小写，支持部分匹配，例如，“wind”或“devin”匹配 Windsurf，“gemini”或“anti”匹配 Gemini 和 Antigravity）。如果没有提供参数或未匹配到任何 Agent，请使用 AskUserQuestion（或 Agent 的同等交互式提示工具）显示可选菜单。

第 1 级：完整支持，具有专用格式和路径

Agent	格式说明
Claude Code	纯 Markdown，每个文件少于 200 行。不存在 CLAUDE.md 时会读取 AGENTS.md
Cursor	必须使用 YAML frontmatter：alwaysApply: true，扩展名为 .mdc
Windsurf（现为 Devin Desktop）	纯 Markdown，全局文件不超过 6,000 个字符，每个工作区规则文件不超过 12,000 个字符。工作区规则位于 .devin/rules/，并带有 trigger frontmatter 字段
GitHub Copilot	纯 Markdown，路径为 .github/copilot-instructions.md
Gemini CLI 和 Antigravity CLI	纯 Markdown。2026-06-18，Antigravity CLI 取代了 Gemini CLI，供免费用户及 Google AI Pro 和 Ultra 用户使用
Roo Code	纯 Markdown
Amp	与 Claude Code 格式相同
Codex (OpenAI)	纯 Markdown，使用 AGENTS.md，总大小限制为 32 KiB
Cline	纯 Markdown
OpenCode	纯 Markdown
Continue	纯 Markdown
Trae	纯 Markdown

第 2 级：支持通用 Markdown 格式

Agent	格式说明
Goose	纯 Markdown
Augment	纯 Markdown
Kilo Code	纯 Markdown

其他 / 通用

对于未列出的任何 Agent：将纯 Markdown 写入用户指定的路径。请向用户询问输出路径。

请参阅 references/agent-targets.md，了解各 Agent 的格式、路径、限制和测试说明。

---

阶段 2：选择作用范围

使用可选菜单（AskUserQuestion 或 Agent 的同等交互式提示工具），询问用户要为哪个作用范围生成规则：

作用范围	说明	典型路径（以 Claude Code 为例）
全局	应用于每个项目的用户级规则。个人工作流偏好。	~/.claude/CLAUDE.md
项目（团队共享）	提交到代码仓库。整个团队遵循的共享约定。	.claude/rules/team-rules.md
项目（开发者专属）	仅在本地供此开发者使用，由 git 忽略。叠加在团队规则之上的个人偏好。	.claude/rules/dev-rules.md

请参阅 references/agent-targets.md，了解各 Agent 与作用范围组合对应的确切路径。

如果目标文件已存在，请显示可选菜单，询问用户：

1. 覆盖：用生成的内容完全替换该文件
2. 合并：在现有内容下方追加生成的内容，中间以 --- 分隔
3. 取消：取消操作并保持文件不变

---

阶段 3：工作流问卷

始终通过结构化交互式菜单提问，绝不要使用纯文本。如果可以使用 AskUserQuestion，请使用它。否则，请使用 Agent CLI 提供的同等交互式提示工具。用户应从选项列表中选择，而不是阅读大段文字后自行输入答案。如果工具支持，每次调用最多批量提出 4 个相互独立的问题。如果某个问题的选项超过 4 个，请展示最常见的 4 个选项，并用“其他”选项或自由文本作为其余选项。

等待用户回答后，再继续下一批问题。

范围矩阵

范围决定要询问哪些问题：

#	问题	分组	全局	团队共享	开发者专属
Q1	主要技术栈	A：项目背景	是	是	跳过
Q2	目录结构	A：项目背景	是	是	跳过
Q3	构建／运行命令	A：项目背景	是	是	跳过
Q4	代码质量标准	B：代码规范	是	是	跳过
Q5	测试理念	B：代码规范	是	是	跳过
Q6	错误处理	B：代码规范	是	是	跳过
Q7	安全与密钥	B：代码规范	是	是	跳过
Q8	依赖管理	B：代码规范	是	是	跳过
Q9	分支规范	C：版本控制	是	是	跳过
Q10	提交规范	C：版本控制	是	是	跳过
Q11	PR/MR 创建	C：版本控制	是	是	跳过
Q12	规划习惯	D：Agent 工作流	是	跳过	是
Q13	自主程度	D：Agent 工作流	是	跳过	是
Q14	行为边界（绝不执行）	D：Agent 工作流	是	跳过	是
Q15	Agent 并行处理	D：Agent 工作流	是	跳过	是
Q16	任务跟踪	D：Agent 工作流	是	跳过	是
Q17	自我改进	D：Agent 工作流	是	跳过	是
Q18	沟通风格	E：沟通	是	跳过	是
Q19	人设／角色扮演	E：沟通	是	跳过	是
Q20	其他备注	F：自由填写	是	是	是

团队共享规则涵盖整个团队共同认可的技术标准（技术栈、目录结构、命令、质量、测试、错误处理、安全、依赖、分支、提交、PR）。开发者专属规则涵盖个人工作流偏好（规划风格、自主程度、行为边界、并行处理、任务跟踪、自我改进、沟通风格、人设）。全局范围包含所有内容。

问题参考、描述、选项映射和输出示例，请参阅 references/questionnaire.md。

建议的分批方式

对于全局范围（全部 20 个问题），建议按以下方式分批：

• 第 1 批（分组 A）：Q1（技术栈）、Q2（目录）、Q3（命令，自由文本）
• 第 2 批（分组 B，第 1 部分）：Q4（质量）、Q5（测试）、Q6（错误处理）、Q7（安全）
• 第 2a 批（后续问题）：Q4 文档后续问题
• 第 3 批（分组 B+C）：Q8（依赖）、Q9（分支）、Q10（提交）、Q11（PR）
• 第 3a 批（后续问题）：Q10 共同作者后续问题
• 第 4 批（分组 D，第 1 部分）：Q12（规划）、Q13（自主程度）、Q14（行为边界）、Q15（并行处理）
• 第 5 批（分组 D+E）：Q16（跟踪）、Q17（自我改进）、Q18（沟通）、Q19（人设）
• 第 5a 批（后续问题）：Q16 外部工具后续问题
• 最后一批：Q20（其他备注，自由文本）

对于其他范围，请调整分批方式，跳过范围矩阵中标记为“跳过”的问题。

问题参考

提问前请阅读 references/questionnaire.md。其中包含每个问题的准确文本、目的、选项表，以及每个答案对应的规则。请根据这些选项表构建每个菜单。

以下问题需要用户进行不止一次菜单选择：

问题	处理方式
Q1 主要技术栈	提供最相关的 4 个技术栈（PHP+Symfony、TypeScript+React、Python+Django、Go、Rust、Java+Spring）；自动添加“其他”。如果选择“其他”，请让用户具体说明
Q3 构建/运行命令	自由填写，可留空。逐字包含在 ## Commands 章节中；如果留空则省略该章节
Q4 代码质量标准	后续询问：文档级别
Q10 提交规范	后续询问：Agent 是否应将自身添加为共同作者
Q14 边界	如果选择“自定义”，请询问用户的禁止事项列表，并在其前加上 NEVER
Q16 任务跟踪	后续询问：外部工具（Jira、Linear、GitHub Issues、None）。如果选择了某项，则生成引用该工具的规则
Q19 Persona	如果选择“是”，请让用户描述 Persona（可输入任意内容）；如果内容晦涩难懂，则使用网络搜索。生成一段描述、5-8 条口头禅，以及一条硬性约束：始终优先保证准确性，Persona 只是点缀而非实质内容（每次回复最多使用一条口头禅，且不得连续重复）
Q20 附加评论	自由填写。逐字包含在末尾的 ## Additional Rules 章节中；如果用户跳过，则省略该章节

---

阶段 4：生态系统发现

在运行时扫描已安装的技能、Agent 和团队。不要依赖硬编码清单。

扫描流程

使用平台的标准位置扫描已安装的技能、Agent 和团队。不同 AI 编码工具会将技能存储在不同位置。请检查第一阶段中所选 Agent 对应的用户级和项目级目录。

常见的 SKILL.md（技能）、*.md Agent 定义文件和 *.md 团队定义文件扫描位置：

• 用户级技能/Agent/团队目录（因平台而异）
• 项目级 .{agent}/skills/、.{agent}/agents/、.{agent}/teams/
• 插件缓存目录（如果平台使用插件系统）

如果安装了 using-ecosystem 技能，请调用它。该技能提供适配平台的发现命令。

对于找到的每个文件，读取 YAML frontmatter（name、description），并构建以下规则章节：

1. 技能章节：每个已安装技能对应一条项目符号：当 [description 中的触发条件] 时 -> 使用 /skill-name
2. 自定义 Agent 章节：列出 Agent 及其能力摘要（只读还是 worktree、专用型还是角色型）
3. Agent 角色章节：列出角色 Agent 及其职责领域
4. 团队章节：列出预先组合的团队及其负责人和适用场景

AI 编码 Agent 本身是主要的发现机制：它会读取技能 frontmatter（name、description），以判断何时激活各项技能。对于 Agent 不确定该使用哪项技能或哪个 Agent 的情况，using-ecosystem 技能是次要顾问。若已安装，它会提供匹配启发式和链式调用模式。

并行化附加规则

如果用户在 Q15 中选择了“始终并行化”或“大型任务并行化”，请将此行添加到自定义 Agent 章节：

When delegating to agent teams, prefer using custom agents over general-purpose when a matching agent exists.

---

阶段 5：组装并写入

根据问卷答案生成规则文件内容。结构取决于范围。

控制输出篇幅

每轮都会读取指令文件，文件越长，遵循得越少。针对仓库上下文文件的研究发现，无论是自动生成还是手动编写的文件，通常都不会提高任务成功率，还会多消耗 20% 以上的推理资源；而具体指令则能得到良好遵循。如果已安装 context-engineering 技能，请使用它。简而言之：

• 每一行都必须能避免 Agent 在没有这条指令时会犯的错误。删除 Agent 本来就会遵循的内容，以及可由代码检查器或格式化工具强制执行的内容。
• 不要添加 Agent 能自行读取的仓库概览、目录树或技术栈列表。命令、不明显的约定和严格禁令才值得保留。
• 将下方模板中的通用区块（Core Principles、Code Change Hygiene、Don't Guess、Knowledge Sources）视为可选内容。将它们放在最后；文件接近篇幅上限时，优先删除这些区块。
• Claude Code：每个文件控制在约 200 行以内。使用 @path 导入可以整理文件，但不会降低成本。将只适用于仓库部分区域的重要规则移至按路径限定的规则（.claude/rules/*.md，并带有 paths: 前置元数据），这样只有在修改匹配的文件时才会加载。其他工具也有类似的限定机制（Cursor 的 .cursor/rules、Copilot 的 .github/instructions、Devin 的 .devin/rules，使用 glob 触发）。
• 必须每次都遵守的规则应放在钩子、代码检查器或测试中，而不是本文件里。
• 必须在压缩后保留的规则应放在始终加载的文件中。
• 在 agent-targets 中查看目标工具的篇幅限制，并在第 6 阶段报告文件大小。
• 请用户使用 instruction-auditor Agent，检查现有指令文件的大小、矛盾、过时规则、机密和隐藏的 Unicode 字符。

全局范围结构

# Global Rules

## Commands
[Build/run commands from Q3, only if provided; omit section if blank]

## Code Quality
[Quality bar from Q4 + documentation follow-up]
[Stack conventions from Q1]
[Directory structure from Q2]
[Error handling from Q6]
[Elegance check: "For non-trivial changes, pause and ask: is there a more elegant way?"]

## Testing
[Testing rules from Q5]

## Security
[Security practices from Q7]
[Dependency management from Q8]

## Version Control
[Branch rules from Q9]
[Commit rules from Q10 + co-authorship follow-up]
[PR creation from Q11]

## Workflow
[Planning rules from Q12]
[Autonomy rules from Q13]
[Boundaries from Q14]
[Parallelization rules from Q15]
[Re-plan rule: "If an approach fails or hits unexpected complexity, stop and re-plan immediately"]

## Communication
[Communication style from Q18]

## Task Management
[Tracking from Q16 + external tool follow-up]
[Self-improvement from Q17]

## Core Principles
- Simplicity first: make every change as simple as possible
- Root causes only: no temporary fixes, find and fix the real problem
- Minimal blast radius: touch only what's necessary
- Prove it works: never mark done without verification

## Code Change Hygiene
- Read before editing: always read and understand existing code before modifying it
- Minimal diffs: make the smallest change that solves the problem, no drive-by cleanups
- Follow existing patterns: match the codebase's style, naming, and structure
- One task at a time: complete the requested task, don't fix unrelated issues or "improve" adjacent code
- Prefer editing over creating: always prefer modifying an existing file over creating a new one
- Search before creating: before creating a new file, search for an existing one that serves a similar purpose
- Never create documentation files unless explicitly asked
- No premature abstractions: don't introduce interfaces, base classes, or design patterns unless the current task demands them
- No backwards-compatibility shims: when replacing code, remove the old version entirely
- Remove dead code: don't leave commented-out code, unused imports, or orphaned functions

## Don't Guess
- Don't fabricate URLs, file paths, API endpoints, or names. Search or ask if unsure
- Don't assume unstated requirements: implement only what was requested
- Don't assume project architecture: explore and verify before making decisions
- Ask when stuck: a clarifying question is cheaper than a wrong implementation
- If an approach fails or hits unexpected complexity, stop and re-plan immediately

## Safety Baseline
- Never commit secrets, .env files, API keys, or credentials to version control
- Never force push to main/master
- Never delete branches without explicit approval
- Never modify CI/CD pipelines without explicit approval

## Knowledge Sources
- When a topic is covered by an installed skill, use the skill first. It contains curated, verified content
- When a topic is NOT covered by installed skills, search the web for the official documentation of the technology (e.g., symfony.com for Symfony, php.net for PHP, react.dev for React)
- Prefer official docs over blog posts, Stack Overflow, or AI-generated summaries. Official sources are the most accurate and current
- When recommending MCPs, skills, or packages to install, always prefer official providers (e.g., Anthropic, Vercel, framework authors) over community alternatives
- When no official option exists, prefer well-maintained community options with high adoption and recent activity

## Skills

CRITICAL: When a situation matches an installed skill, you MUST use it. Do not rely on general knowledge when a dedicated skill exists. Skills contain curated reference material that is more precise than answers generated from scratch. Skipping a relevant skill is like ignoring documentation you already have open.

[Auto-generated from Phase 4 runtime scan. One line per installed skill.]
When [trigger from description] -> use /skill-name
...

## Custom Agents
[If specialist agents are found during Phase 4 scan, list them with descriptions and capabilities. If none found, omit this section entirely.]

## Agent Roles
[If role agents are installed (per Phase 4), list them here with the domain they own. If none, omit this section entirely.]

## Persona
[If Q19 = Yes: persona description, catchphrases, and constraint. If No, omit this section entirely.]

## Recommended (not installed)
- Install [skill] from krzysztofsurdy/code-virtuoso: [what it helps with]

项目团队共享结构

# Project Rules

## Commands
[Build/run commands from Q3, only if provided]

## Stack & Conventions
[Stack conventions from Q1]
[Quality bar from Q4 + documentation follow-up]
[Directory structure from Q2]
[Error handling from Q6]

## Testing
[Testing rules from Q5]

## Security
[Security practices from Q7]
[Dependency management from Q8]

## Version Control
[Branch rules from Q9]
[Commit rules from Q10 + co-authorship follow-up]
[PR creation from Q11]

## Core Principles
- Simplicity first: make every change as simple as possible
- Root causes only: no temporary fixes, find and fix the real problem
- Minimal blast radius: touch only what's necessary
- Prove it works: never mark done without verification

## Code Change Hygiene
- Read before editing: always read and understand existing code before modifying it
- Minimal diffs: make the smallest change that solves the problem, no drive-by cleanups
- Follow existing patterns: match the codebase's style, naming, and structure
- One task at a time: complete the requested task, don't fix unrelated issues or "improve" adjacent code
- Prefer editing over creating: always prefer modifying an existing file over creating a new one
- Search before creating: before creating a new file, search for an existing one that serves a similar purpose
- Never create documentation files unless explicitly asked
- No premature abstractions: don't introduce interfaces, base classes, or design patterns unless the current task demands them
- No backwards-compatibility shims: when replacing code, remove the old version entirely
- Remove dead code: don't leave commented-out code, unused imports, or orphaned functions

## Don't Guess
- Don't fabricate URLs, file paths, API endpoints, or names. Search or ask if unsure
- Don't assume unstated requirements: implement only what was requested
- Don't assume project architecture: explore and verify before making decisions
- Ask when stuck: a clarifying question is cheaper than a wrong implementation

## Safety Baseline
- Never commit secrets, .env files, API keys, or credentials to version control
- Never force push to main/master
- Never delete branches without explicit approval
- Never modify CI/CD pipelines without explicit approval

## Knowledge Sources
- When a topic is covered by an installed skill, use the skill first. It contains curated, verified content
- When a topic is NOT covered by installed skills, search the web for the official documentation of the technology
- Prefer official docs over blog posts, Stack Overflow, or AI-generated summaries
- When recommending MCPs, skills, or packages to install, always prefer official providers over community alternatives
- When no official option exists, prefer well-maintained community options with high adoption and recent activity

项目开发专用结构

# Dev Rules

## Workflow
[Planning rules from Q12]
[Autonomy rules from Q13]
[Boundaries from Q14]
[Parallelization rules from Q15]

## Communication
[Communication style from Q18]

## Task Management
[Tracking from Q16 + external tool follow-up]
[Self-improvement from Q17]

## Persona
[If Q19 = Yes: persona description, catchphrases, and constraint. If No, omit.]

Agent 专用格式

写入前应用以下转换：

Cursor：使用 YAML 前置元数据包裹整个内容：

---
alwaysApply: true
---

[content here]

Windsurf (Devin Desktop)：检查字符数。全局文件限制为 6,000 个字符，每个工作区规则文件限制为 12,000 个字符。如果文件超出限制，请压缩章节（删除示例、缩短描述），直到符合限制。工作区规则文件以 trigger: always_on 前置元数据开头。全局文件和根目录下的 AGENTS.md 不添加前置元数据。

Antigravity CLI：AGENTS.md 和 GEMINI.md 不添加前置元数据。.agents/rules/ 中的文件必须以声明 trigger 的前置元数据开头（这些规则使用 always_on），否则 Antigravity 会丢弃这些文件。规则文件超过 24 KB 时会被截断。

Claude Code / Amp（全局）：控制在 200 行以内。在末尾添加说明：For project-specific rules, use .claude/rules/*.md files.

Claude Code（项目）：如果仓库中已有 AGENTS.md 且没有 CLAUDE.md，Claude Code 会自行读取 AGENTS.md。添加 CLAUDE.md 或 CLAUDE.local.md 后，它只会读取 CLAUDE.md 文件，因此新建的 CLAUDE.md 应通过 @AGENTS.md 导入该文件。

Codex：在项目根目录使用 AGENTS.md 文件命名约定。合并后的指令链达到 32 KiB 后，Codex 会停止添加文件。

其他工具：保持原样，使用纯 Markdown。

规则生成示例

每个回答都会对应一段包含 2–5 条规则的简短内容。references/questionnaire.md 列出了全部 20 个问题的每个回答对应的生成规则，以及完整的人物设定输出示例（海盗船长、脾气暴躁的资深工程师）。组装上述章节时，请加载该文件并直接采用其中的规则要点，不要自行编写。

阶段 6：确认

写入文件后，执行以下操作：

1. 向用户显示完整生成内容
2. 显示写入文件的文件路径
3. 显示行数和字符数
4. 如果应用了任何 Agent 专属限制（例如 Windsurf 字符数限制、Claude 行数限制），说明精简了哪些内容
5. 说明文件大小占工具预算的比例，并提供 instruction-auditor Agent，供之后审查
6. 提问：“结束前，您还想修改什么吗？”

---

错误处理

• 如果目标目录不存在，则创建该目录
• 如果用户在问卷期间中止，则放弃所有进度，不要写入不完整文件
• 如果用户在阶段 4 报告没有安装任何 code-virtuoso 插件，则完全跳过 Skills、Custom Agents 和 Agent Roles 部分，并附上简短的“推荐（未安装）”列表，指向 tool-using-ecosystem 和 agents-virtuoso，作为初始安装项
• 如果没有安装 using-ecosystem，不要编造生态清单。询问用户已安装哪些内容
• 对于项目范围，在写入前确认当前目录位于 git 仓库中

---

参考文件

参考文件	内容
agent-targets	每个 Agent 和范围的输出路径、格式要求、限制和测试步骤（阶段 1、2 和 5）
questionnaire	Q1-Q20 的问题文本、选项表、答案到规则的映射以及角色示例（阶段 3 和 5）