| name | vibe-coding |
| description | AI辅助编程规范。当涉及代码组织、架构设计、重构、新功能开发、协作流程、测试、文档时使用。 |
Vibe Coding 规范
让 AI 更容易理解代码，让人更容易审查 AI 的输出。
架构原则
文件大小
| 行数 |
状态 |
AI 效果 |
| < 300 |
✅ 理想 |
完整理解 |
| 300-500 |
✅ 良好 |
基本理解 |
| 500-800 |
⚠️ 警告 |
需拆分 |
| > 800 |
❌ 禁止 |
丢失上下文 |
拆分原则
| 原则 |
说明 |
| 单一职责 |
一个文件只做一件事 |
| 目录代替大文件 |
db.py → db/ 目录 |
| 统一导出 |
__init__.py 暴露公共接口 |
| 禁止循环导入 |
用依赖注入解决 |
拆分示例
database.py (2000行)
↓
database/
├── base.py # 基类
├── user_repo.py # 用户
├── order_repo.py # 订单
└── __init__.py # 导出
上下文管理
| 策略 |
说明 |
| 文件精简 |
< 500 行 |
| 子代理隔离 |
独立任务用子代理 |
| 定期压缩 |
/compact |
| 任务拆分 |
复杂任务分多步 |
协作流程
需求描述
✅ "在 user_service.py 添加 delete_user(user_id: int) -> bool"
❌ "帮我加个删除功能"
开发流程
人描述需求 → 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 维护
重构检查清单
开始前：
完成后：
配置管理重构
核心原则
配置外部化：代码中不应出现环境相关的硬编码值
| 类型 |
硬编码示例 |
正确做法 |
| 路径 |
/home/user/data |
环境变量/配置文件 |
| 凭证 |
API_KEY="abc123" |
密钥管理服务 |
| 端口 |
port = 8080 |
配置参数 |
| 主机 |
localhost, 127.0.0.1 |
配置参数 |
检查方法
全局搜索 → 分层验证 → 反向确认 → 部署配置
搜索策略
| 目标 |
搜索模式 |
预期 |
| 绝对路径 |
以 / 或 C:\ 开头的字符串 |
0 |
| 敏感词 |
KEY, SECRET, PASSWORD, TOKEN |
仅配置文件 |
| 网络地址 |
localhost, IP 地址, 端口号 |
仅配置文件 |
分层覆盖
| 范围 |
说明 |
遗漏风险 |
| 所有代码包 |
递归检查所有模块 |
⭐⭐⭐ 高 |
| 独立脚本 |
工具脚本、启动脚本 |
⭐⭐⭐ 高 |
| 配置文件 |
部署配置、环境配置 |
⭐⭐ 中 |
关键：不要假设某些模块"不需要配置化"
常见遗漏
| 模式 |
原因 |
解决 |
| 非核心模块 |
只重构主目录 |
全局搜索 |
| 工具脚本 |
认为是"临时代码" |
一视同仁检查 |
| 配置不同步 |
代码改了配置没改 |
反向验证 |
验证流程
1. 定义配置 → 集中管理所有配置项
↓
2. 引用配置 → 代码中只读取配置
↓
3. 搜索硬编码 → 全局搜索残留 ← **关键**
↓
4. 部署注入 → 运行时提供配置值
完整性检查