coding-style

一套通用编码风格 + 验证纪律，一条命令装进市面上各家 AI agent 工具，让 CodeBuddy/WorkBuddy、Trae、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Windsurf 都按同一套规矩写代码。

内容本身管两件事：

• 注释去 AI 味：禁方括号标签、禁文档腔 JSDoc、禁术语卖弄，有用的话压成一行大白话。
• 优化不能把能跑的功能改坏：任何清理/重构都要用真实数据验证，从源码抠真实函数体跑真实输入，不认手写复刻品。

零依赖，只用 Node 内置模块，Node >= 16。

安装

npm i -g coding-style

用法

装到所有 agent

coding-style install --agent all

主目录相关的文件（CodeBuddy/WorkBuddy、Trae、Claude）直接落到 ~ 下，项目相关的（Cursor、Copilot、Gemini、Windsurf、AGENTS.md）落到你当前所在的项目目录。所以建议先 cd 到项目根目录再执行。

已存在的文件默认不覆盖

目标位置已经有同名文件时，install 默认跳过，打印一行提示就过：

[跳过] C:\Users\you\.claude\CLAUDE.md 已存在，用 --force 覆盖

这样你手写过的 CLAUDE.md、.cursorrules 不会被静默冲掉。确认要覆盖就加 --force：

coding-style install --agent all --force

想先看看哪些会写、哪些会跳，--dry-run 和 --force 可以一起用：

coding-style install --agent all --dry-run          # 看默认行为
coding-style install --agent all --force --dry-run  # 看加了 --force 会覆盖哪些

只装某一个

coding-style install --agent cursor
coding-style install --agent claude
coding-style install --agent copilot

先看看会写哪些文件

coding-style install --agent all --dry-run

全铺到一个临时目录里预览

coding-style install --agent all --target ./cs-preview

各文件会按自己的相对路径铺开（比如 cs-preview/.github/copilot-instructions.md），确认没问题再真装。

看内容

coding-style show                  # 包根的 SKILL.md（带 YAML frontmatter）
coding-style show --agent claude   # Claude Code 用的那份
coding-style show --agent cursor   # Cursor 用的那份

抠真实函数体做验证

这是风格文件里"验证纪律"那节的配套工具，从真实源码里按花括号配对抠出函数完整源码，跳过字符串、注释、正则字面量。

# 打印函数源码
coding-style extract src/app.js parseVehicle

# 抠出来后走 node --check 校验语法
coding-style extract src/app.js parseVehicle --syntax

# 挂到最小桩上跑一段真实表达式，JSON 打印结果
coding-style extract src/app.js parseVehicle --eval "parseVehicle('X16_A')"

包里同时带了 Python 版 scripts/extract_function.py 和 Node 版 scripts/extract_function.mjs，两版逻辑一致，CLI 走的是 Node 版，所以不用装 Python。

--eval 只对 function NAME(){} 这种写法可靠

打印和 --syntax 对下面几种写法基本都能用，但 --eval 要把抠出来的片段挂成一个能直接调的函数，所以只有 function NAME(){} 声明式写法能原样跑通：

| 写法 | 打印 | --syntax | --eval | | --- | --- | --- | --- | | function NAME(){} | 能 | 能 | 能 | | const NAME = function(){} | 能 | 能 | 报 NAME is not defined | | const NAME = (x) => {} | 能 | 能 | 报 NAME is not defined | | 对象方法简写 NAME(){} | 能 | 报 SYNTAX_FAIL | 报 Unexpected token '{' |

后三种要跑 --eval，先把抠出来的片段自己包一层再跑，比如前两种在前面补个 const、方法简写改写成 function NAME(...){...}。

这里有个坑值得单说：撞上 NAME is not defined 时，很容易顺手以为是自己源码有问题，然后换个"看起来能过"的样例重跑——那就正好掉进 SKILL 验证纪律里说的"编个长得像的名字骗自己"。报这个错说明是工具的边界，不是你的代码有问题，别改样例，改包法。

各 agent 部署位置

| agent 名 | 内容文件 | 落点 | | --- | --- | --- | | codebuddy / workbuddy | content/SKILL.md | ~/.workbuddy/skills/coding-style/SKILL.md | | trae | content/SKILL.md | ~/.trae/skills/coding-style/SKILL.md | | claude | content/CLAUDE.md | ~/.claude/CLAUDE.md | | cursor | content/.cursorrules | <当前目录>/.cursorrules | | copilot | content/copilot-instructions.md | <当前目录>/.github/copilot-instructions.md | | gemini | content/GEMINI.md | <当前目录>/GEMINI.md | | windsurf | content/windsurf.md | <当前目录>/.windsurfrules | | agents / ag | content/AGENTS.md | <当前目录>/AGENTS.md |

几点要注意：

• codebuddy 和 workbuddy 落的是同一个文件，--agent all 时只写一次。
• Trae 的 skill 目录可能随版本变，装完自己开 Trae 确认认不认这个路径；不认的话把 content/SKILL.md 手动拖进它的 skill 面板。
• Claude Code 的 ~/.claude/CLAUDE.md 是全局的。只想对某个项目生效，把 content/CLAUDE.md 拷到那个项目根目录，项目里的会盖住全局的。
• 这些位置已经有文件的话 install 默认跳过，只有 --force 才覆盖。用 --force 前建议先备份一份。

内容文件说明

content/ 下的文件除 SKILL.md 外正文完全一致，只是文件名和落点不同：

• SKILL.md —— 带 YAML frontmatter，给 CodeBuddy/WorkBuddy、Trae 的 skill 系统用，也可以直接拖进支持 skill 的工具。
• CLAUDE.md / .cursorrules / AGENTS.md / copilot-instructions.md / GEMINI.md / windsurf.md —— 去掉 frontmatter 的纯正文，开头加了一句"以下为通用编码风格，写代码/改代码/审查前遵守"。

想改风格内容，直接改 content/ 里的文件再重新 coding-style install 就行。

发布到 npm

npm login
npm publish

发布前建议先跑一遍自检：

node --check bin/coding-style.js
node --check scripts/extract_function.mjs
node bin/coding-style.js show
node bin/coding-style.js install --agent all --target ./cs-preview
npm pack --dry-run     # 看看真正会打进包的文件列表

名字被占了怎么办

coding-style 这个名字在 npm 上可能已经被人占了。npm publish 报 403 / Package name too similar to existing package 就改成带 scope 的名字，把 package.json 里的 name 换掉：

{
  "name": "@你的npm用户名/coding-style"
}

scope 包默认是私有的，公开发布要加参数：

npm publish --access public

装的时候名字跟着变，但命令名还是 coding-style（bin 字段决定的，不受包名影响）：

npm i -g @你的npm用户名/coding-style
coding-style install --agent all

License

MIT