【OpenCode系统性指南】第4篇：AGENTS.md进阶：教AI你的编码规范

概念图

引言

当你第一次运行 /init 命令，Claude Code 会自动扫描项目并生成一份 AGENTS.md 文件。这份自动生成的配置确实能帮助 AI 理解项目基础结构，但很快你会发现它远远不够——AI 生成的代码风格不统一、命名随意、缺少测试、Git 提交信息混乱……问题接踵而至。本文将深入讲解如何通过 AGENTS.md 进阶配置，真正教会 AI 你的编码规范，让它成为懂你风格的得力助手。

一、官方生成的AGENTS.md为什么不够用

自动生成的局限性

Claude Code 的 /init 命令会分析 package.json、README.md、现有代码结构等信息，生成一份基础配置。这份配置通常包含：

项目描述和目录结构
基本的安装和运行命令
技术栈识别（React、Vue、Python 等）

然而，自动生成无法捕捉以下关键信息：

编码风格偏好：你喜欢单引号还是双引号？用不用分号？缩进是 2 空格还是 4 空格？这些细节 AI 无法从代码结构推断。

团队约定：分支命名规则、提交信息格式、PR 审核流程——这些是团队内部约定的，不会体现在代码中。

业务领域知识：你的项目涉及特定领域的业务逻辑，比如电商的订单状态流转、金融的交易风控规则，这些知识需要显式告诉 AI。

安全与合规要求：哪些 API 密钥不能提交、敏感数据如何处理、日志记录规范——这些往往没有代码痕迹。

一个真实的例子

假设你运行 /init 后得到这样的 AGENTS.md：

# My Project

React + TypeScript 项目

## 开发命令
- npm install
- npm run dev
- npm test

这看起来还行，但当你让 AI 创建一个新组件时，可能会得到：

组件没有 TypeScript 接口定义
使用了你团队不推荐的 Class 组件
样式写成了内联形式
忘记添加必要的错误处理

这就是自动生成的局限性——它只知道"是什么"，不知道"应该怎样"。

二、项目级 vs 全局规则

Claude Code 提供了多层次的规则配置体系，理解这个体系是进阶配置的基础。

规则优先级（从高到低）

层级	文件位置	作用范围	典型用途
Managed Policy	系统级目录	组织内所有用户	公司安全策略
命令行参数	CLI 临时指定	当前会话	临时覆盖
Local Project	`./CLAUDE.local.md`	仅自己、当前项目	个人偏好
Project Rules	`./.claude/rules/*.md`	团队共享	领域特定规则
Project Memory	`./CLAUDE.md`	团队共享	项目核心配置
User Memory	`~/.claude/CLAUDE.md`	仅自己、所有项目	个人编码风格

项目级配置：CLAUDE.md

项目根目录的 CLAUDE.md 是最重要的配置文件，它随代码库一起版本控制，所有团队成员共享。这个文件应该包含：

# 电商平台后端

> 基于 Node.js + Express + PostgreSQL 的电商 API 服务

## 项目结构

- `src/controllers/` - API 控制器
- `src/services/` - 业务逻辑层
- `src/models/` - 数据模型
- `src/middlewares/` - 中间件
- `src/utils/` - 工具函数
- `tests/` - 测试文件

## 开发命令

- 安装：`pnpm install`
- 开发：`pnpm dev`
- 测试：`pnpm test`
- 构建：`pnpm build`
- 代码检查：`pnpm lint`

## 编码规范

- 使用 ESLint + Prettier
- 单引号，无分号
- 2 空格缩进
- 异步函数必须 try-catch

## Git 规范

- 分支：`feature/xxx`、`fix/xxx`、`hotfix/xxx`
- 提交：`type(scope): message`
- 提交前必须通过 lint 和 test

全局级配置：User Memory

全局配置位于 ~/.claude/CLAUDE.md，适用于你所有的项目。这里放你的个人偏好：

# 个人编码偏好

## 代码风格
- 优先使用函数式编程
- 避免过深的嵌套，早返回
- 变量命名要有语义

## 注释习惯
- 复杂逻辑必须注释
- 公共函数必须有 JSDoc
- 避免无意义的注释

## 测试习惯
- 新功能必须有单元测试
- 测试覆盖率 > 80%

规则目录：.claude/rules/

当配置变得复杂时，可以拆分到 .claude/rules/ 目录下。每个文件可以针对特定路径生效：

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有端点必须包含输入验证
- 使用标准错误响应格式
- 敏感数据不得记录日志

这个 YAML frontmatter 中的 paths 字段指定了规则只对 src/api/ 下的 TypeScript 文件生效，避免无关文件加载这些规则占用上下文。

三、10个实用规则模板

下面是 10 个开箱即用的规则模板，覆盖最常见的场景。

1. TypeScript 项目规则

---
paths:
  - "src/**/*.ts"
  - "src/**/*.tsx"
---

# TypeScript 开发规范

## 代码风格
- 使用函数式/声明式代码，避免类
- 使用单引号，无分号
- 2 空格缩进
- 定义明确的接口/类型

## 命名约定
- 组件：PascalCase
- 变量/函数：camelCase
- 常量：UPPER_SNAKE_CASE
- 文件：kebab-case

## 最佳实践
- 优先使用 `interface` 而非 `type`
- 避免使用 `any`，使用 `unknown` 并进行类型守卫
- 使用可选链 `?.` 和空值合并 `??`

2. React 项目规则

---
paths:
  - "src/components/**/*.tsx"
---

# React 开发规范

## 组件结构
- 使用函数组件和 Hooks
- 组件顶部声明状态，底部声明副作用
- Props 必须定义 TypeScript 接口

## 样式处理
- 优先使用 Tailwind CSS
- 避免内联样式（除非动态计算）

## 性能优化
- 使用 `React.memo` 包装纯组件
- 使用 `useCallback` 和 `useMemo` 避免不必要渲染
- 列表项必须使用稳定的 key

3. Python 项目规则

---
paths:
  - "**/*.py"
---

# Python 开发规范

## 代码风格
- 遵循 PEP 8 规范
- 使用 Black 格式化（行长 88 字符）
- 使用 isort 排序导入
- 4 空格缩进

## 类型注解
- 所有函数必须有类型注解
- 使用 `typing` 模块的泛型类型

## 最佳实践
- 使用 f-string 格式化字符串
- 使用 context manager 处理资源
- 编写 docstring（Google 风格）

4. 代码风格规则

# 代码风格规范

## 格式化
- 使用 Prettier 自动格式化
- 单引号，无尾逗号
- 最大行长 100 字符

## 命名
- 布尔值用 `is`、`has`、`should` 前缀
- 事件处理用 `handle` 前缀
- 私有属性用 `_` 前缀

## 注释
- TODO 格式：`// TODO(author): description`
- FIXME 格式：`// FIXME: description`
- 复杂算法必须有解释注释

5. Git 提交规范

# Git 工作流规范

## 分支命名
- `feature/功能描述` - 新功能
- `fix/bug描述` - Bug 修复
- `hotfix/紧急修复` - 线上紧急修复
- `refactor/重构描述` - 代码重构
- `docs/文档描述` - 文档更新

## 提交信息格式

<body>


### 类型说明
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档
- `style`: 格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建/工具

## 提交前检查
- 运行 `pnpm lint` 确保无错误
- 运行 `pnpm test` 确保测试通过
- 检查是否有敏感信息

6. 测试规范

# 测试规范

## 测试框架
- 前端：Vitest + React Testing Library
- 后端：Jest + Supertest

## 测试命名
- 测试文件：`*.test.ts` 或 `*.spec.ts`
- 测试描述：使用中文或英文，保持一致

## 测试结构
```typescript
describe('模块名', () => {
  describe('函数/组件名', () => {
    it('应该返回期望结果', () => {
      // arrange
      // act
      // assert
    })
  })
})

覆盖率要求

行覆盖率 > 80%
分支覆盖率 > 70%
核心业务逻辑 100%


### 7. 文档规范

```markdown
# 文档规范

## README 结构
1. 项目简介
2. 快速开始
3. 开发指南
4. API 文档
5. 部署说明
6. 常见问题

## 代码注释
- 公共函数必须有 JSDoc
- 复杂逻辑必须有行内注释
- 避免陈述显而易见的内容

## API 文档
- 使用 OpenAPI/Swagger
- 包含请求/响应示例
- 说明错误码含义

8. 安全规范

# 安全规范

## 密钥管理
- 永远不要提交 `.env` 文件
- 使用环境变量存储敏感信息
- 生产密钥使用密钥管理服务

## 代码安全
- 用户输入必须验证和清洗
- SQL 查询使用参数化
- 避免在日志中记录敏感数据

## 依赖安全
- 定期运行 `pnpm audit`
- 及时更新有漏洞的依赖
- 锁定依赖版本

9. 性能规范

# 性能规范

## 前端优化
- 图片使用 WebP 格式
- 路由懒加载
- 使用虚拟列表处理大数据
- 防抖/节流高频事件

## 后端优化
- 数据库查询添加索引
- 使用分页避免全量查询
- Redis 缓存热点数据
- 压缩响应数据

## 性能监控
- 记录慢查询（>100ms）
- 监控内存使用
- 设置性能预算

10. 团队协作规范

# 团队协作规范

## Code Review
- PR 描述必须包含改动说明
- 单个 PR 控制在 400 行以内
- 审核者在 24 小时内响应
- 使用建设性的语气

## 沟通约定
- 技术讨论记录在 Issue/PR
- 重要决策更新到文档
- 每日站会同步进度

## 发布流程
1. 合并到 main 分支
2. 自动运行 CI
3. 部署到测试环境验证
4. 发布到生产环境
5. 监控告警

AGENTS.md 配置示例

四、让AI记住你的代码风格

使用 Auto Memory 自动学习

Claude Code 有一个强大的自动内存机制。当你在开发过程中发现 AI 的输出需要调整时，直接告诉它：

记住：我们项目不使用 class 组件，全部用函数组件

Claude 会自动将这条规则记录到 ~/.claude/projects/<project>/memory/ 目录。下次会话时会自动加载这些学习到的规则。

定期审查和更新

AGENTS.md 应该是"活的文档"。建议：

每周审查：检查是否有新的模式需要添加到规则中。

删除过时规则：技术栈升级后，旧规则可能不再适用。

团队协作维护：将团队讨论得出的最佳实践同步到配置中。

使用符号链接共享规则

如果你有多个项目使用相同的技术栈，可以用符号链接共享规则：

# 创建通用规则目录
mkdir -p ~/.claude/shared-rules

# 在项目中创建符号链接
ln -s ~/.claude/shared-rules/typescript.md .claude/rules/

这样更新一次，所有项目都会同步。

分离个人和团队配置

使用 CLAUDE.local.md 存储个人偏好：

# 个人本地配置

- 我的 IDE 是 VS Code
- 偏好在浏览器中调试
- 使用 pnpm 而非 npm

这个文件会被自动 gitignore，不会影响团队其他成员。

小结

官方 /init 生成的 AGENTS.md 只能识别项目结构，无法理解编码规范和团队约定
规则优先级从高到低：Managed Policy > 命令行 > Local > Project Rules > Project Memory > User Memory > Auto Memory
使用 .claude/rules/ 目录拆分规则，配合 paths 字段实现路径特定规则
保持 AGENTS.md 简洁（300行以内），定期审查更新，让它成为"活的文档"

【OpenCode系统性指南】第4篇：AGENTS.md进阶：教AI你的编码规范

【OpenCode系统性指南】第4篇：AGENTS.md进阶：教AI你的编码规范

引言

一、官方生成的AGENTS.md为什么不够用

自动生成的局限性

一个真实的例子

二、项目级 vs 全局规则

规则优先级（从高到低）

项目级配置：CLAUDE.md

全局级配置：User Memory

规则目录：.claude/rules/

三、10个实用规则模板

1. TypeScript 项目规则

2. React 项目规则

3. Python 项目规则

4. 代码风格规则

5. Git 提交规范

6. 测试规范

覆盖率要求

8. 安全规范

9. 性能规范

10. 团队协作规范

四、让AI记住你的代码风格

使用 Auto Memory 自动学习

定期审查和更新

使用符号链接共享规则

分离个人和团队配置

小结

延伸阅读