ai-code-rules

A lightweight rule system for AI-assisted coding in real-world codebases.

一套把项目隐性知识沉淀成 AI 可执行规则的轻量模板。

---

这是什么

ai-code-rules 是一套「双入口 + 六目录」的规则结构模板,把项目的隐性约定沉淀成 AI 可消费的规则文件。

• 双入口:AGENTS.md + CLAUDE.md,分别面向通用 agent 和 Claude Code
• 六目录:00-global / 01-context / 02-architecture / 03-components / 04-patterns / 05-ai

每个目录解决一类失控:

目录	它在防什么
00-global/	AI 不知道项目的硬底线
01-context/	AI 不懂业务,凭技术常识瞎写
02-architecture/	AI 不知道技术骨架,写出"通用代码"
03-components/	AI 用错组件、混用组件、自造组件&不复用已有组件
04-patterns/	AI 单步对、整体错
05-ai/	AI 重复推销已否决方案

这不是什么

• ❌ 不是一个"装上就能用"的 npm 包
• ❌ 不是给所有项目的通用规则结构
• ❌ 不是 AI 提示词工程最佳实践
• ❌ 不是给小项目的方案 —— 小项目用不上,一份 AGENTS.md 就够了

适用场景

强适用(满足 2 条以上):

• 团队已经把 AI 用进真实开发,不是偶尔玩玩
• 项目存在非显性的工程约束(自定义组件库 / 历史包袱 / 微前端 / 特殊状态管理)
• AI 反复生成"不符合项目规范但能跑"的代码

可参考(满足 1 条):

• 代码量 10 万行以上
• 新人理解主流程超过 1 周
• 同类页面被重复实现多次
• code review 经常在纠正结构问题,而不是业务问题

可能用不上:简单 CRUD 项目,一份 AGENTS.md 就够了,不需要六目录。

快速上手

# 1. Clone 模板
git clone https://github.com/weijianjunwjj/ai-code-rules.git my-project-rules
cd my-project-rules

# 2. 删掉 .git,作为你项目的起点
rm -rf .git

# 3. 把 .template 文件复制为正式文件并填充
cp AGENTS.md.template AGENTS.md
cp CLAUDE.md.template CLAUDE.md
cp docs/00-global/principles.md.template docs/00-global/principles.md
cp docs/00-global/tech-stack.md.template docs/00-global/tech-stack.md
cp docs/00-global/non-goals.md.template docs/00-global/non-goals.md
# 其他文件按需复制

# 4. 从 AGENTS.md 和 docs/00-global/non-goals.md 开始写起

推荐写作顺序:

1. 先写 AGENTS.md —— 提炼 5–10 条项目红线
2. 写 docs/00-global/non-goals.md —— 告诉 AI 不做什么
3. 写第一份 ADR —— 记录最重要的一个架构决策
4. 边踩坑边写 docs/05-ai/anti-patterns.md
5. 其他目录按需补全

不要一上来就写满六目录。 六目录是增长结构,不是首日交付清单。

目录结构

.
├── AGENTS.md.template
├── CLAUDE.md.template
└── docs/
    ├── 00-global/
    │   ├── principles.md.template
    │   ├── tech-stack.md.template
    │   └── non-goals.md.template
    ├── 01-context/
    │   └── README.md
    ├── 02-architecture/
    │   ├── README.md
    │   └── decisions/
    │       ├── 0000-adr-template.md
    │       └── 0001-example-adr.md
    ├── 03-components/
    │   └── README.md
    ├── 04-patterns/
    │   ├── README.md
    │   └── list-page-pattern.md.template
    └── 05-ai/
        ├── README.md
        ├── anti-patterns.md.template
        ├── forbidden-suggestions.md.template
        └── review-checklist.md.template

注:docs/04-patterns/list-page-pattern.md.template 偏 Vue 中后台风格,这是因为本仓库源自一个 Vue 2.6 项目。其他技术栈可作为结构参考,内容自行替换。

五条维护规则

1. anti-patterns 随 review 触发更新 —— 发现 AI 重复触犯同一类问题就补一条最小记录:错误代码 + 为什么错 + 推荐写法。不强制日更,但发现就补。
2. ADR 只增不删 —— 旧 ADR 标 Superseded by ADR-XXXX,保留决策历史轨迹。
3. 每个 pattern 都要有反向引用 —— 引用对应的 ADR 和组件文档,孤立文档不算数。
4. 高频组件和易误用组件必须有错例对照 —— 低频组件可降级为软规则,不强求全覆盖。
5. 季度做一次「AI 失败档案」复盘 —— 抽 20 条 AI 误生成案例,反推哪个目录文档没写到位,补上去。

设计哲学

把项目知识从隐性变成显性 —— 从"老员工脑子里"变成"AI 可消费的资产"。

这件事跨项目、跨技术栈、跨 AI 代际。

工具会过时,方法会迭代,判断力不会。

License

MIT © weijianjun