Vibe Coding 规范
让 AI 更容易理解代码，让人更容易审查 AI 的输出。
架构原则
文件大小
| 行数 | 状态 | AI 效果 |
|---|---|---|
| < 300 | ✅ 理想 | 完整理解 |
| 300-500 | ✅ 良好 | 基本理解 |
| 500-800 | ⚠️ 警告 | 需拆分 |
| > 800 | ❌ 禁止 | 丢失上下文 |
拆分原则
| 原则 | 说明 |
|---|---|
| 单一职责 | 一个文件只做一件事 |
| 目录代替大文件 | db.py → db/ 目录 |
| 统一导出 | __init__.py 暴露公共接口 |
| 禁止循环导入 | 用依赖注入解决 |
拆分示例
code
database.py (2000行) ↓ database/ ├── base.py # 基类 ├── user_repo.py # 用户 ├── order_repo.py # 订单 └── __init__.py # 导出
上下文管理
| 策略 | 说明 |
|---|---|
| 文件精简 | < 500 行 |
| 子代理隔离 | 独立任务用子代理 |
| 定期压缩 | /compact |
| 任务拆分 | 复杂任务分多步 |
协作流程
需求描述
code
✅ "在 user_service.py 添加 delete_user(user_id: int) -> bool" ❌ "帮我加个删除功能"
开发流程
code
人描述需求 → AI 输出测试用例 → 人确认 → AI 写实现 → 人审查
代码审查清单
- • 逻辑正确
- • 无安全漏洞
- • 无过度设计
- • 测试覆盖
错误处理
| 原则 | 示例 |
|---|---|
| 自定义异常 | UserNotFoundError 而非 Exception |
| docstring 声明 | Raises: UserNotFoundError |
| 边界处处理 | 入口处 try-catch，内部传播 |
| 日志记录 | 关键错误必须记录 |
测试策略
| 场景 | 判断方式 | 策略 |
|---|---|---|
| Bug 修复 | fix/修复/bug | 必须先写复现测试 |
| 重构 | 重构/refactor | 必须先有测试 |
| 新功能 | 默认 | 代码先行，上线前补 |
测试先行触发词：
- •"这个功能很重要，先写测试"
- •"TDD 方式开发"
Mock 策略
| 场景 | 策略 |
|---|---|
| 外部 API | 必须 mock |
| 数据库 | 测试库或 mock |
| 时间 | mock datetime |
文档规范
| 变更类型 | 更新位置 |
|---|---|
| 新功能 | SKILL.md |
| 架构变更 | CLAUDE.md |
| API 变更 | docstring |
| 开发规范 | 本 skill |
CLAUDE.md 维护
- •保持精简
- •删除过时内容
- •新思路及时沉淀
重构检查清单
开始前：
- • 文件 > 500 行？
- • 多个职责？
- • AI 经常改错？
- • 测试覆盖够？
完成后：
- • 文件 < 500 行
- • 单一职责
- • 导入清晰
- • 测试通过
配置管理重构
核心原则
配置外部化：代码中不应出现环境相关的硬编码值
| 类型 | 硬编码示例 | 正确做法 |
|---|---|---|
| 路径 | /home/user/data | 环境变量/配置文件 |
| 凭证 | API_KEY="abc123" | 密钥管理服务 |
| 端口 | port = 8080 | 配置参数 |
| 主机 | localhost, 127.0.0.1 | 配置参数 |
检查方法
code
全局搜索 → 分层验证 → 反向确认 → 部署配置
搜索策略
| 目标 | 搜索模式 | 预期 |
|---|---|---|
| 绝对路径 | 以 / 或 C:\ 开头的字符串 | 0 |
| 敏感词 | KEY, SECRET, PASSWORD, TOKEN | 仅配置文件 |
| 网络地址 | localhost, IP 地址, 端口号 | 仅配置文件 |
分层覆盖
| 范围 | 说明 | 遗漏风险 |
|---|---|---|
| 所有代码包 | 递归检查所有模块 | ⭐⭐⭐ 高 |
| 独立脚本 | 工具脚本、启动脚本 | ⭐⭐⭐ 高 |
| 配置文件 | 部署配置、环境配置 | ⭐⭐ 中 |
关键：不要假设某些模块"不需要配置化"
常见遗漏
| 模式 | 原因 | 解决 |
|---|---|---|
| 非核心模块 | 只重构主目录 | 全局搜索 |
| 工具脚本 | 认为是"临时代码" | 一视同仁检查 |
| 配置不同步 | 代码改了配置没改 | 反向验证 |
验证流程
code
1. 定义配置 → 集中管理所有配置项 ↓ 2. 引用配置 → 代码中只读取配置 ↓ 3. 搜索硬编码 → 全局搜索残留 ← **关键** ↓ 4. 部署注入 → 运行时提供配置值
完整性检查
- • 所有硬编码已移至配置
- • 配置项有默认值
- • 部署配置完整
- • 使用类型安全配置工具