让 AI 写代码不再「胡来」：claude-rules 编码规范库深度解析

想象这样一个场景：你给 AI 下达一个看似简单的任务——「在用户列表页面加一个导出功能」。AI 爽快地写完了 300 行代码，看起来逻辑清晰，命名规范。但当你仔细审查时才发现：它用了已经废弃的类组件写法，在循环里直接改 state，导出函数和 UI 代码搅在一起，注释里还藏着一行被注释掉但从未删除的旧逻辑。这不是 AI 的问题——这是提示词（Prompt）的边界问题。没有明确的编码规范，AI 只能从已有代码中「模仿风格」，而 legacy 项目里的坏味道代码自然会传染给它。 claude-rules 正是为解决这个痛点而生的开源项目：它是一套面向 AI 编码助手的模块化编码规范模板库，通过「基础原则 + 语言规则 + 框架规范」三层叠加的方式，为任何项目生成针对性的 CLAUDE.md，让 AI 在每次对话中都严格遵循一致的代码质量标准。

背景：为什么需要给 AI 写「编码规范」？

Claude Code、Cursor、GitHub Copilot 等 AI 编程工具已经深度融入开发者的日常工作。然而，当开发者面对一个新项目时，AI 的表现往往令人失望：它倾向于「模仿」现有代码的风格，即使这些风格本身是有问题的。例如，在满是 var 声明的旧 JavaScript 项目中，AI 会继续用 var 而不是 const；在代码行数没有限制的遗留库里，AI 会写出 500 行的函数；在没有类型注解的 Python 项目中，AI 也会跳过类型标注。这种「向最差情况看齐」的行为，本质上是因为 AI 没有收到足够具体的编码指令。 claude-rules 的作者 lifedever（GitHub ID: 3143306）自 2024 年开始维护这个项目，核心理念只有一条：

「不要模仿旧代码，按规范重构。」 这个原则看似反直觉——为什么要让 AI「无视」现有代码？作者的答案很直接：legacy 代码的坏味道（如 God Class、深嵌套、魔法数字）是技术债务，而不是标准。AI 的价值在于写出干净的代码，而不是延续旧项目的错误。

目录结构：三明治式的规范叠加

claude-rules 的目录结构设计得像一个三明治，从底层到顶层依次叠加，优先级也随之递增： 第一层 — base（必选）：所有项目的通用规范，包括：

core.md：核心原则，涵盖对旧代码的态度（不模仿而是重构）、代码质量硬指标（函数不超过 30 行、文件不超过 300 行、嵌套不超过 3 层、参数不超过 4 个）、命名规范、架构原则等。
git.md：Git 提交信息规范，采用 <type>(<scope>): <subject> 格式，type 包括 feat/fix/docs/style/refactor/perf/test/chore。 第二层 — languages（按需选择）：根据项目语言选择对应规则文件，支持 10 种语言：TypeScript、JavaScript、Java、Kotlin、Swift、Python、HTML、CSS、Go、Rust。每种语言都有针对性的规范，例如 TypeScript 禁止使用 any（必须用 unknown 配合类型守卫），Python 要求所有公开函数必须有类型注解并使用 ruff 进行格式化。 第三层 — frameworks（按需选择）：根据项目使用的框架选择规则文件，支持 5 种框架：Vue、React、SwiftUI、Spring Boot、Tauri。每种框架都有其独特的最佳实践，例如 React 规则禁止类组件（必须用函数组件 + Hooks）、禁止 prop drilling 超过 2 层；Spring Boot 规则要求严格分层（Controller 不含业务逻辑、Repository 不含业务逻辑）。 优先级规则：framework > language > base，即框架的规则优先于语言的，语言优先于基础的。当规范冲突时，具体规则覆盖通用规则。

核心功能：从手动组合到智能自动化

claude-rules 提供了两种使用方式，满足不同场景的需求： 方式一：命令行手动组合（适合任意 AI 工具）

# 克隆仓库
git clone https://github.com/lifedever/claude-rules.git
# 按需组合规则文件，生成 CLAUDE.md
cat claude-rules/base/core.md claude-rules/base/git.md \\
  claude-rules/languages/typescript.md \\
  claude-rules/frameworks/vue.md > CLAUDE.md

这种方式的优势是通用性——任何 AI 编程工具（Cursor、Copilot、Antigravity 等）都可以读取项目根目录的 CLAUDE.md 并遵守其中的规范。 方式二：Claude Code 插件（推荐）（仅限 Claude Code）

# 添加插件市场
claude plugin marketplace add lifedever/claude-rules
# 安装插件
claude plugin install init-claude-rules@claude-rules
# 重启 Claude Code，在项目目录中运行
/init-rules

插件的工作流程非常智能：

自动检测技术栈：扫描项目目录，根据 tsconfig.json、package.json、pom.xml、Cargo.toml 等配置文件识别语言和框架。
用户确认：展示检测结果，允许用户调整（如漏检了某个框架）。
组装规范：从插件本地文件读取对应规范，按 base → language → framework 顺序拼接。
生成 CLAUDE.md：写入项目根目录，覆盖前会询问确认，避免误操作。插件还支持增量更新：当上游仓库有新规则时，运行 claude plugin marketplace update claude-rules 即可同步本地缓存，对已有 CLAUDE.md 的项目再次执行 /init-rules 即可热更新规范。

代码质量规范示例

claude-rules 的每条规则都配有「禁止 / 正确」对比示例，这种格式让 AI 更容易理解和执行。以 TypeScript 规范为例：

// 禁止：使用 any 类型
function parse(data: any): any { ... }

// 正确：unknown + 类型守卫
function parse(data: unknown): ParseResult { ... }

再比如 Python 规范中的类型注解要求：

# 禁止：无类型注解
def process(data, config):
    ...

# 正确：完整类型注解
def process(data: list[dict[str, Any]], config: ProcessConfig) -> ProcessResult:
    ...

这种「规则即示例」的编写风格，比泛泛的「请保持代码规范」要有效得多。AI 看到具体代码对比后，能够更准确地理解规范意图并应用到新代码中。

局限性：不完美之处

作为一个纯文本规则库，claude-rules 也有其局限：

强制力依赖 AI 自觉：AI 有时会「忘记」规范，尤其是在长对话后半段。插件版本的规范持久性优于一次性生成的 CLAUDE.md，但仍然无法做到 100% 强制执行。
规则覆盖有边界：目前的语言支持以主流语言为主，小众语言（如 Ruby、PHP）尚未覆盖。框架方面也缺少 Django、Next.js 等高频框架的专项规范。
更新同步成本：上游规则更新后，已生成的 CLAUDE.md 不会自动同步，需要手动重新运行 /init-rules 或重新 cat 组合。
非可执行项目：作为纯 Markdown 规则库，无法通过 CI/CD 自动检查代码是否符合规范，只能靠人工审查或接入额外的 lint 工具链。

行业意义：AI 编程规范化的第一步

随着 Claude Code、Cursor 等 AI 编程工具的普及，如何让 AI 写出高质量、可维护的代码，正在成为团队级开发的新挑战。claude-rules 代表了一种重要的趋势：从「信任 AI 的直觉」转向「明文定义代码标准」，让 AI 的输出从「能跑就行」升级为「符合团队规范」。从 GitHub 数据来看，该项目已获得 186 颗星，说明这一需求在开发者社区中具有一定普遍性。随着 Claude Code Skill 生态的发展，预计会有更多类似的「AI 工具配置库」涌现，claude-rules 作为先行者，有望成为这一细分领域的标杆项目。 作者头像 claude-rules 作者头像 图1：claude-rules GitHub 仓库 作者主页：https://github.com/lifedever 项目官网：https://www.lifedever.com/claude-rules/

让 AI 写代码不再「胡来」：claude-rules 编码规范库深度解析

背景：为什么需要给 AI 写「编码规范」？

「不要模仿旧代码，按规范重构。」 这个原则看似反直觉——为什么要让 AI「无视」现有代码？作者的答案很直接：legacy 代码的坏味道（如 God Class、深嵌套、魔法数字）是技术债务，而不是标准。AI 的价值在于写出干净的代码，而不是延续旧项目的错误。

目录结构：三明治式的规范叠加

claude-rules 的目录结构设计得像一个三明治，从底层到顶层依次叠加，优先级也随之递增： 第一层 — base（必选）：所有项目的通用规范，包括：

core.md：核心原则，涵盖对旧代码的态度（不模仿而是重构）、代码质量硬指标（函数不超过 30 行、文件不超过 300 行、嵌套不超过 3 层、参数不超过 4 个）、命名规范、架构原则等。
git.md：Git 提交信息规范，采用 <type>(<scope>): <subject> 格式，type 包括 feat/fix/docs/style/refactor/perf/test/chore。 第二层 — languages（按需选择）：根据项目语言选择对应规则文件，支持 10 种语言：TypeScript、JavaScript、Java、Kotlin、Swift、Python、HTML、CSS、Go、Rust。每种语言都有针对性的规范，例如 TypeScript 禁止使用 any（必须用 unknown 配合类型守卫），Python 要求所有公开函数必须有类型注解并使用 ruff 进行格式化。 第三层 — frameworks（按需选择）：根据项目使用的框架选择规则文件，支持 5 种框架：Vue、React、SwiftUI、Spring Boot、Tauri。每种框架都有其独特的最佳实践，例如 React 规则禁止类组件（必须用函数组件 + Hooks）、禁止 prop drilling 超过 2 层；Spring Boot 规则要求严格分层（Controller 不含业务逻辑、Repository 不含业务逻辑）。 优先级规则：framework > language > base，即框架的规则优先于语言的，语言优先于基础的。当规范冲突时，具体规则覆盖通用规则。

核心功能：从手动组合到智能自动化

claude-rules 提供了两种使用方式，满足不同场景的需求： 方式一：命令行手动组合（适合任意 AI 工具）

# 克隆仓库
git clone https://github.com/lifedever/claude-rules.git
# 按需组合规则文件，生成 CLAUDE.md
cat claude-rules/base/core.md claude-rules/base/git.md \\
  claude-rules/languages/typescript.md \\
  claude-rules/frameworks/vue.md > CLAUDE.md

# 添加插件市场
claude plugin marketplace add lifedever/claude-rules
# 安装插件
claude plugin install init-claude-rules@claude-rules
# 重启 Claude Code，在项目目录中运行
/init-rules

插件的工作流程非常智能：

自动检测技术栈：扫描项目目录，根据 tsconfig.json、package.json、pom.xml、Cargo.toml 等配置文件识别语言和框架。
用户确认：展示检测结果，允许用户调整（如漏检了某个框架）。
组装规范：从插件本地文件读取对应规范，按 base → language → framework 顺序拼接。
生成 CLAUDE.md：写入项目根目录，覆盖前会询问确认，避免误操作。插件还支持增量更新：当上游仓库有新规则时，运行 claude plugin marketplace update claude-rules 即可同步本地缓存，对已有 CLAUDE.md 的项目再次执行 /init-rules 即可热更新规范。

代码质量规范示例

claude-rules 的每条规则都配有「禁止 / 正确」对比示例，这种格式让 AI 更容易理解和执行。以 TypeScript 规范为例：

// 禁止：使用 any 类型
function parse(data: any): any { ... }

// 正确：unknown + 类型守卫
function parse(data: unknown): ParseResult { ... }

再比如 Python 规范中的类型注解要求：

# 禁止：无类型注解
def process(data, config):
    ...

# 正确：完整类型注解
def process(data: list[dict[str, Any]], config: ProcessConfig) -> ProcessResult:
    ...

这种「规则即示例」的编写风格，比泛泛的「请保持代码规范」要有效得多。AI 看到具体代码对比后，能够更准确地理解规范意图并应用到新代码中。

局限性：不完美之处

作为一个纯文本规则库，claude-rules 也有其局限：

强制力依赖 AI 自觉：AI 有时会「忘记」规范，尤其是在长对话后半段。插件版本的规范持久性优于一次性生成的 CLAUDE.md，但仍然无法做到 100% 强制执行。
规则覆盖有边界：目前的语言支持以主流语言为主，小众语言（如 Ruby、PHP）尚未覆盖。框架方面也缺少 Django、Next.js 等高频框架的专项规范。
更新同步成本：上游规则更新后，已生成的 CLAUDE.md 不会自动同步，需要手动重新运行 /init-rules 或重新 cat 组合。
非可执行项目：作为纯 Markdown 规则库，无法通过 CI/CD 自动检查代码是否符合规范，只能靠人工审查或接入额外的 lint 工具链。