项目规范

项目规范是代码项目从创建到维护全生命周期中应遵循的约定和最佳实践。良好的规范能降低协作摩擦、减少低级错误、提升代码可维护性。本目录汇集了个人在实际项目中沉淀的规范方案。

注：本文档提及的项目主要是指代码项目。

规范分类

仓库结构规范

项目根目录应包含以下基础文件：

• README.md - 项目说明、快速上手指南
• .gitignore - 版本控制忽略规则
• LICENSE - 开源许可证（如适用）
• CHANGELOG.md - 变更日志（中大型项目）
• 配置文件 - 如 .editorconfig、pyproject.toml、package.json 等

代码风格与格式化

统一代码风格是团队协作的基础。推荐通过工具自动化而非人工约束：

• 格式化工具：Prettier（前端）、Black/Ruff（Python）、clang-format（C/C++）
• Lint 工具：ESLint、Ruff、clippy 等
• 配置文件入库：将 .prettierrc、ruff.toml 等配置提交到仓库，确保团队统一

Git 规范

• 分支策略：根据团队规模选择 Git Flow、GitHub Flow 或 Trunk-Based
• 提交信息：遵循 Conventional Commits 格式（type(scope): description）
• Pre-commit hooks：使用 pre-commit 或 husky 在提交前自动检查格式和 lint

CI/CD 规范

在仓库中定义 CI 流水线配置（如 .github/workflows/、.gitlab-ci.yml），至少覆盖：

• 代码格式检查
• 单元测试
• 构建验证

实践原则

• 自动化优先：能用工具检查的规范，不要靠人工 review
• 渐进式引入：对老项目先从格式化和 lint 开始，逐步完善
• 文档化约定：项目特有的约定写入 CONTRIBUTING.md 或 CLAUDE.md