用途:让 NVCF 文档保持平实、一致,便于外部读者理解。目标是写出智能体或贡献者无需私有上下文即可执行的简短文档,并避免破坏 grep 与 diff 工具的排版 Unicode 字符和噪声强调格式。
适用场景:本仓库中任何新增或修改的公开 Markdown;AGENTS.md、CLAUDE.md、SKILL.md、README、计划与指南;GitHub issue 正文、提交信息与 PR 描述;因其他原因正在改动的既有文档。
主要规则:
- 不用 Markdown 加粗做强调,不用 ...、...、原始 HTML 的 <b> 或 <strong>。用标题、列表和反引号表示路径、命令、环境变量与标识符。
- 文档和面向用户的文字中不用 emoji。
- 不用 em-dash(U+2014)和 en-dash(U+2013)。把想法拆成两句,或用逗号、分号、括号、冒号。
- 提交的正文只用 ASCII。避免弯引号、省略号字符、不换行空格、箭头等排版 Unicode。用 -> 代替箭头符号,用 ... 代替单字符省略号。代码块和引用的固定内容除外。
- 简洁。用短句和直接措辞,删掉填充与重复,尽量一句一个意思。
- 优先用列表做易扫读结构。无序项用项目符号,涉及顺序、优先级或稳定规则引用时用编号列表。仅当列能帮助比较、状态、选项权衡或矩阵决策时才用表格,不要把短列表做成表格。
- 易懂。面向广泛读者时首次出现即定义缩写,优先具体例子而非抽象术语。
- 面向 GitHub 读者。使用公开名称、公开路径和公开行为,用用户可见的变更原因替代私有证据。
- 智能体指引要可执行。说明何时使用技能、先检查什么、运行什么命令、完成的标准是什么。不要加入临时分支状态、PR 队列、合并顺序说明或私有路由细节。
- 避免含糊的智能体用语。除非能增加具体条件,否则删除 ensure、leverage、robust、comprehensive、where applicable、as needed 等填充词。
编辑既有文件:若文件已使用加粗、emoji、em-dash、en-dash 或非 ASCII 标点,在你因其他原因改动该文件时,或用户要求做风格整理时进行规范化。不要为修风格而扩大到无关目录树。
限制:规则针对本仓库中由智能体编辑的正文。上游文档在原生合并前保留自己的风格。目前没有针对正文的自动 linter,靠评审发现风格问题。
例外:逐字引用的内容,如上游 LICENSE 文本、引用的错误或用户粘贴内容;由生成器控制格式的生成文件,必要时在生成器中修风格;由外部提交信息汇总的自动生成变更日志或发布说明,应修源提交而非汇总文件。