通用项目脚手架（Universal Project Scaffold）

概述

项目初始化是决定长期维护成本的关键时刻。缺少 .gitignore 的仓库、没有 lint 的代码库、没有测试目录的项目——这些问题越晚修复成本越高。本技能提供跨技术栈的脚手架最佳实践，覆盖目录结构、配置文件、代码质量工具链和持续集成（CI）基础设施。

标准目录结构

project-root/
├── src/              # 源代码
├── tests/            # 测试文件，与 src/ 镜像结构
├── docs/             # 项目文档
├── scripts/          # 构建、部署、数据迁移等脚本
├── .github/          # GitHub Actions 工作流
│   └── workflows/
├── .gitignore        # Git 忽略规则
├── .editorconfig     # 编辑器统一配置
├── .env.example      # 环境变量模板（不含真实值）
├── README.md         # 项目说明
├── LICENSE           # 许可证
└── Makefile          # 常用命令入口（可选）

必备配置文件

代码质量工具链（Linting / Formatting）

CI 基础模板（GitHub Actions）

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup  # 根据技术栈选择 Node / Python / Go 等
      - name: Install dependencies
      - name: Lint
      - name: Test

关键原则：第一个提交（commit）就应包含 CI 配置，即使只运行 lint。

Pre-commit 钩子（Hooks）

使用 pre-commit 框架在提交前自动执行质量检查：

1. 安装：pip install pre-commit 或 brew install pre-commit
2. 创建 .pre-commit-config.yaml 配置文件
3. 执行 pre-commit install 激活钩子
4. 推荐钩子：trailing-whitespace、end-of-file-fixer、detect-secrets、check-merge-conflict

环境变量管理（.env.example 模式）

# .env.example — 复制为 .env 并填入真实值
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_KEY=your-api-key-here
DEBUG=false

管理规则：

1. 创建 .env.example，列出所有环境变量名和示例值
2. 将 .env 加入 .gitignore，绝不提交真实密钥
3. 项目启动脚本检查必需变量是否存在，缺失时报错退出
4. 文档中说明每个变量的用途和获取方式

决策矩阵：Monorepo vs Polyrepo

工作流

1. 使用脚手架工具或模板仓库创建项目骨架
2. 配置 .gitignore、.editorconfig、LICENSE
3. 设置代码质量工具（linter + formatter）并写入配置文件
4. 创建 .env.example，定义所有环境变量
5. 配置 pre-commit 钩子并执行 pre-commit install
6. 编写最小化 CI 工作流（至少包含 lint + test）
7. 完善 README.md（安装、运行、贡献指南）
8. 首次提交，确认 CI 通过

必须做（MUST DO）

• 第一个提交就包含 .gitignore 和 README.md
• 配置至少一个 lint 工具并添加到 CI
• 创建 tests/ 目录，即使暂时为空
• 提供 .env.example，不让新成员猜配置
• 提交 lock 文件（package-lock.json、uv.lock 等）确保可复现构建

禁止做（MUST NOT DO）

• 禁止将 .env、密钥文件、node_modules、__pycache__ 提交到版本控制
• 禁止跳过 .gitignore——"以后再加"意味着永远不加
• 禁止使用无 lock 文件的依赖管理
• 禁止在没有格式化配置的情况下开始多人协作
• 禁止将 CI 配置推迟到"以后再说"

常见错误