# vibe-coding

> AI辅助编程规范。当涉及代码组织、架构设计、重构、新功能开发、协作流程、测试、文档时使用。

- Author: caichenghang
- Repository: cch96/claude-plugins
- Version: 20260107173705
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/cch96/claude-plugins
- Web: https://mule.run/skillshub/@@cch96/claude-plugins~vibe-coding:20260107173705

---

---
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 维护

- 保持精简
- 删除过时内容
- 新思路及时沉淀

## 重构检查清单

**开始前**：
- [ ] 文件 > 500 行？
- [ ] 多个职责？
- [ ] AI 经常改错？
- [ ] 测试覆盖够？

**完成后**：
- [ ] 文件 < 500 行
- [ ] 单一职责
- [ ] 导入清晰
- [ ] 测试通过

## 配置管理重构

### 核心原则

**配置外部化**：代码中不应出现环境相关的硬编码值

| 类型 | 硬编码示例 | 正确做法 |
|------|-----------|----------|
| 路径 | `/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. 部署注入 → 运行时提供配置值
```

### 完整性检查

- [ ] 所有硬编码已移至配置
- [ ] 配置项有默认值
- [ ] 部署配置完整
- [ ] 使用类型安全配置工具