The Vibe Coding skill is a comprehensive framework designed to optimize AI-assisted software engineering. It establishes rigorous standards for code organization, architectural modularity, and human-AI collaboration workflows. By enforcing file size limits, clear context management, and Test-Driven Development (TDD) principles, it ensures that AI-generated code remains maintainable, scalable, and easy to review, significantly reducing technical debt in AI-augmented projects.

When should I use vibe-coding?

vibe-coding is useful in the following scenarios: • Refactoring monolithic legacy files into modular directory structures to improve AI context window efficiency and code readability. • Implementing a 'Test-First' workflow where the AI generates reproduction test cases before performing bug fixes or feature updates. • Standardizing error handling by enforcing custom exceptions and docstring declarations to make AI-generated logic more robust. • Automating the externalization of hardcoded configurations and sensitive credentials into environment variables for secure, multi-environment deployment. • Maintaining dynamic project documentation (CLAUDE.md) to keep the AI aligned with the latest architectural decisions and development norms.

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. 部署注入 → 运行时提供配置值

完整性检查

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

vibe-coding

When & Why to Use This Skill

Use Cases