专题：Claude Code 工作流系统学习
关键词：Claude Code, 脚手架, 项目初始化, 模板, cookiecutter, boilerplate, 项目结构, 配置生成
一、核心工作流总览
项目脚手架与初始化是软件开发的首个关键环节，决定了项目的可维护性、可扩展性和团队协作效率。Claude Code 借助其强大的代码生成能力，可以在数分钟内完成传统上需要数小时乃至数天的手动搭建工作。本笔记系统梳理完整工作流，涵盖项目模板生成、框架脚手架、CLAUDE.md 初始化、配置文件生成、Git 初始化和 CI 初始化六大板块。
工作流执行顺序：
① 规划项目需求 → ② 选择技术栈 → ③ 生成项目结构 → ④ 创建 CLAUDE.md 项目记忆 → ⑤ 生成配置文件 → ⑥ 初始化 Git 仓库 → ⑦ 配置 CI/CD → ⑧ 验证项目完整性
1.1 Claude Code 项目初始化核心原则
- 可复现性：项目结构应具备模板化特征，同一类型项目可反复使用
- 渐进式：先搭建骨架，再填充业务逻辑，避免一开始过度设计
- 约定优于配置：遵循语言/框架社区最佳实践，减少配置决策负担
- 文档即代码：CLAUDE.md 作为项目记忆，随代码一起版本管理
"脚手架的本质不是简单地复制粘贴，而是将架构决策转化为可重复执行的代码知识。"
二、项目模板生成
项目模板生成是整个工作流的起点。Claude Code 可以依据用户的自然语言描述，自动创建完整的项目目录结构和基础文件。不同于传统 cookiecutter 模板的静态替换，Claude Code 可以根据项目特点动态调整结构。
2.1 标准项目目录规范
Claude Code 遵循各语言社区推荐的目录规范。以下是最常见的三种结构模式：
| 项目类型 | 推荐结构 | 适用场景 |
|---|
| 单体应用（Monolith） | 分层架构（controller/service/repository） | 中大型后端服务 |
| 模块化单体 | 按业务功能分模块（auth/payment/order） | 业务边界清晰的项目 |
| 前后端分离 | client/ + server/ 双目录 | Web 应用 + API 服务 |
2.2 用 Claude Code 生成项目结构
通过自然语言描述即可让 Claude Code 生成完整项目结构。例如：
# 告诉 Claude Code 创建 Python 后端项目的结构
/init
# 或者直接使用 Prompt：
"创建一个 FastAPI 项目脚手架，要求：
- src/ 源码目录，按 domain 组织模块
- tests/ 单元测试和集成测试
- alembic/ 数据库迁移
- docker/ Docker 构建文件
- scripts/ 工具脚本
- docs/ 项目文档"
Claude Code 会生成完整的目录树：
my-fastapi-project/
├── src/
│ ├── api/ # 路由层
│ │ ├── v1/
│ │ │ ├── auth.py
│ │ │ ├── users.py
│ │ │ └── __init__.py
│ │ └── deps.py # 依赖注入
│ ├── core/ # 核心配置
│ │ ├── config.py
│ │ ├── security.py
│ │ └── database.py
│ ├── domain/ # 业务领域
│ │ ├── auth/
│ │ ├── users/
│ │ └── common/
│ ├── main.py
│ └── __init__.py
├── tests/
│ ├── api/
│ ├── conftest.py
│ └── fixtures/
├── alembic/
│ ├── versions/
│ └── env.py
├── docker/
│ ├── Dockerfile
│ └── docker-compose.yml
├── scripts/
│ ├── lint.sh
│ └── test.sh
├── docs/
│ └── index.md
├── pyproject.toml
├── .env.example
├── .gitignore
├── CLAUDE.md
└── README.md
2.3 文件命名规范
Claude Code 支持根据不同语言/框架自动采用正确的命名风格：
| 语言/框架 | 命名风格 | 示例 |
|---|
| Python | snake_case | user_service.py, db_config.py |
| TypeScript/JavaScript | camelCase / kebab-case | userService.ts, auth-middleware.ts |
| Java/Kotlin | PascalCase (class) / camelCase (file) | UserService.java, ApplicationConfig.java |
| Go | snake_case | user_service.go, api_handler.go |
| Rust | snake_case | mod.rs, user_service.rs |
最佳实践：在项目初始化时，让 Claude Code 同时生成 CLAUDE.md，记录项目目录结构和命名约定。后续开发中，Claude Code 会自动遵循这些约定创建新文件。
三、框架脚手架
Claude Code 支持主流的 Web 框架和库的脚手架生成。与官方 CLI 工具（如 create-react-app、vue create）相比，Claude Code 的优势在于可以同时集成项目特有的配置、自定义模板和业务逻辑骨架。以下分别讲解五大主流框架的初始化实践。
3.1 React 项目脚手架
React 生态的脚手架需要同时考虑路由、状态管理、样式方案、构建工具等多个维度。使用 Claude Code 可以一站式完成所有集成：
// 用 Claude Code 初始化 React + TypeScript + Vite 项目
// 在空目录下执行以下 prompt：
"创建 React 项目，技术栈：React 18 + TypeScript + Vite + React Router v6 + Zustand + Tailwind CSS"
// Claude Code 会生成完整的项目结构和核心代码：
生成的核心代码示例（路由配置）：
// src/router/index.tsx
import { createBrowserRouter }
from "react-router-dom";
import { lazy, Suspense }
from "react";
import { MainLayout }
from "../layouts";
import { AuthGuard }
from "../components/guards";
import { LoadingScreen }
from "../components/common";
const Dashboard =
lazy(() =>
import(
"../pages/Dashboard"));
const Users =
lazy(() =>
import(
"../pages/Users"));
const Settings =
lazy(() =>
import(
"../pages/Settings"));
const Login =
lazy(() =>
import(
"../pages/Login"));
export const router =
createBrowserRouter([
{
path:
"/",
element: <MainLayout />,
errorElement: <ErrorBoundary />,
children: [
{ index:
true, element: <Dashboard /> },
{
path:
"users",
element: <AuthGuard><Users /></AuthGuard>,
},
{ path:
"settings", element: <Settings /> },
],
},
{ path:
"/login", element: <Login /> },
]);
3.2 Vue 3 项目脚手架
Vue 3 的 Composition API 和 Pinia 状态管理是现代 Vue 开发的标准组合：
// src/stores/auth.ts - Pinia 状态管理示例
import { defineStore } from "pinia";
import { ref, computed } from "vue";
import { authApi } from "@/api/auth";
import { router } from "@/router";
export const useAuthStore = defineStore("auth", () => {
const user = ref<User | null>(null);
const token = ref<string | null>(null);
const isAuthenticated = computed(() => !!token.value);
const isAdmin = computed(() => user.value?.role === "admin");
async function login(credentials: LoginRequest) {
const { user: u, token: t } = await authApi.login(credentials);
user.value = u;
token.value = t;
localStorage.setItem("token", t);
await router.push("/dashboard");
}
async function logout() {
user.value = null;
token.value = null;
localStorage.removeItem("token");
await router.push("/login");
}
return { user, token, isAuthenticated, isAdmin, login, logout };
});
3.3 Django 项目脚手架
Django 项目脚手架需要处理的关键点包括应用拆分、路由配置、数据库配置和环境管理：
# settings/base.py - 分环境配置管理
import os
from pathlib import Path
from datetime import timedelta
BASE_DIR = Path.__file__.resolve().parent.parent.parent
SECRET_KEY = os.getenv("DJANGO_SECRET_KEY")
DEBUG = os.getenv("DJANGO_DEBUG", "False") == "True"
INSTALLED_APPS = [
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"rest_framework",
"corsheaders",
"apps.users",
"apps.orders",
"apps.payments",
]
# REST Framework 配置
REST_FRAMEWORK = {
"DEFAULT_AUTHENTICATION_CLASSES": [
"rest_framework_simplejwt.authentication.JWTAuthentication",
],
"DEFAULT_PERMISSION_CLASSES": [
"rest_framework.permissions.IsAuthenticated",
],
"DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
"PAGE_SIZE": 20,
}
SIMPLE_JWT = {
"ACCESS_TOKEN_LIFETIME": timedelta(minutes=30),
"REFRESH_TOKEN_LIFETIME": timedelta(days=7),
}
3.4 FastAPI 项目脚手架
FastAPI 以其高性能和自动 API 文档著称，适合构建微服务和 API 网关：
# src/main.py - FastAPI 应用入口
from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.trustedhost import TrustedHostMiddleware
from src.core.config import settings
from src.core.database import engine, Base
from src.api.v1 import auth, users, orders
from src.core.logging import setup_logging
@asynccontextmanager
async def lifespan(app: FastAPI):
setup_logging()
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield
await engine.dispose()
app = FastAPI(
title=settings.PROJECT_NAME,
version=settings.VERSION,
docs_url="/api/docs" if settings.ENV != "production" else None,
redoc_url=None,
lifespan=lifespan,
)
# 中间件注册
app.add_middleware(
CORSMiddleware,
allow_origins=settings.CORS_ORIGINS,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
app.add_middleware(
TrustedHostMiddleware,
allowed_hosts=settings.ALLOWED_HOSTS,
)
# 路由注册
app.include_router(auth.router, prefix="/api/v1/auth", tags=["认证"])
app.include_router(users.router, prefix="/api/v1/users", tags=["用户"])
app.include_router(orders.router, prefix="/api/v1/orders", tags=["订单"])
3.5 Express 项目脚手架
Express 的脚手架重点在于中间件管线、路由分层和错误处理体系：
// src/app.ts - Express 应用工厂
import express, { Application } from "express";
import helmet from "helmet";
import cors from "cors";
import compression from "compression";
import { rateLimit } from "express-rate-limit";
import { errorHandler, notFoundHandler } from "./middleware";
import { authRouter, userRouter, orderRouter } from "./routes";
import { logger } from "./utils/logger";
export function createApp(): Application {
const app = express();
// 安全与性能中间件
app.use(helmet());
app.use(cors({ origin: process.env.CORS_ORIGIN?.split(",") }));
app.use(compression());
app.use(express.json({ limit: "10mb" }));
app.use(express.urlencoded({ extended: true }));
// 限流
const limiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 分钟
max: 100,
standardHeaders: true,
legacyHeaders: false,
});
app.use("/api", limiter);
// 路由
app.use("/api/v1/auth", authRouter);
app.use("/api/v1/users", userRouter);
app.use("/api/v1/orders", orderRouter);
// 健康检查
app.get("/health", (_req, res) => {
res.json({ status: "ok", timestamp: new Date().toISOString() });
});
// 错误处理
app.use(notFoundHandler);
app.use(errorHandler);
return app;
}
框架脚手架选择策略：
选择脚手架策略时，应考虑：① 团队技术栈一致性；② 部署环境约束；③ 性能需求；④ 生态成熟度。Claude Code 的优势在于可以根据这些约束条件在初始化时自动做出妥协和决策。
四、CLAUDE.md 初始化
CLAUDE.md 是 Claude Code 的项目记忆文件，记录了项目描述、技术栈、编码规范、命令别名和工作流规则。创建高质量的 CLAUDE.md 是确保 Claude Code 后续正确理解项目的关键。
4.1 CLAUDE.md 的标准结构
# 项目名称
## 项目概述
用一两句话描述项目的目的和功能。
## 技术栈
- 后端：Python 3.12 / FastAPI 0.115 / SQLAlchemy 2.0 / PostgreSQL 16
- 前端：React 18 / TypeScript 5.3 / Vite 5 / Tailwind CSS 3.4
- 基础设施：Docker / Docker Compose / GitHub Actions
- 测试：pytest 8.x / vitest 1.x / Playwright
## 项目结构
src/
api/ - API 路由和处理器
core/ - 核心配置和环境变量
domain/ - 业务逻辑和领域模型
...
tests/
...
## 编码规范
- Python：遵循 PEP 8，使用 ruff 进行 lint
- TypeScript：使用 eslint + prettier，单引号，分号必须
- 所有公开函数和类必须包含 docstring/JSDoc
- 异常必须有明确的错误码和错误信息
## 命令别名
- `dev` → 启动开发服务器
- `test` → 运行测试套件
- `lint` → 运行代码检查和格式化
- `build` → 构建生产版本
- `db-migrate` → 运行数据库迁移
- `db-rollback` → 回滚数据库迁移
## 工作流规则
1. 创建新 API 端点时，同时生成对应的测试用例
2. 修改数据库模型后，自动生成迁移脚本
3. 提交前确保所有测试通过
4. 错误处理使用统一的响应格式
## 构建和测试命令
# 开发
$ uv run uvicorn src.main:app --reload
# 测试
$ uv run pytest -v --cov=src --cov-report=term-missing
# 代码检查
$ uv run ruff check . && uv run mypy src/
# 构建
$ docker build -t my-project .
4.2 生成 CLAUDE.md 的 Prompt 示例
// 让 Claude Code 为已有项目生成 CLAUDE.md
"分析当前项目的以下方面，生成完整的 CLAUDE.md：
1. 根据 package.json / pyproject.toml 等技术文件提取技术栈
2. 扫描 src/ 目录提取项目结构
3. 根据现有代码推断编码规范
4. 从 Makefile / scripts/ 中提取常用命令
5. 总结项目的架构模式和工作流约定"
// 在新项目初始化时直接指定
"创建 CLAUDE.md，记录以下内容：
- 项目名称：电商平台后端
- 技术栈：FastAPI + PostgreSQL + Redis + Docker
- 编码规范：PEP 8，类型注解必须，测试覆盖率 ≥ 80%
- 关键命令：dev/lint/test/build/db-migrate
- 工作流：创建端点前先写测试，数据库变更需迁移"
CLAUDE.md 维护建议：每次引入新的依赖、修改项目结构或更新工作流时，同步更新 CLAUDE.md。可以定期使用 claude-md-management:revise-claude-md 技能自动更新。
五、配置文件生成
现代项目往往需要十几种配置文件协同工作。Claude Code 可以一次性生成全部配置文件，确保它们之间兼容一致。以下是最常见的配置文件集合。
5.1 TypeScript 配置
// tsconfig.json
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"jsx": "react-jsx",
"paths": {
"@/*": ["./src/*"]
},
"baseUrl": ".",
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"lib": ["ESNext", "DOM", "DOM.Iterable"],
"types": ["vitest/globals"]
},
"include": ["src", "vite.config.ts"],
"exclude": ["node_modules", "dist"]
}
5.2 ESLint + Prettier 配置
// eslint.config.js (Flat Config)
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import react from "eslint-plugin-react";
import hooks from "eslint-plugin-react-hooks";
export default tseslint.config(
js.configs.recommended,
...tseslint.configs.recommended,
{
plugins: { react, "react-hooks": hooks },
rules: {
"react-hooks/rules-of-hooks": "error",
"react-hooks/exhaustive-deps": "warn",
"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
},
}
);
// .prettierrc
{
"semi": true,
"singleQuote": true,
"trailingComma": "all",
"printWidth": 100,
"tabWidth": 2,
"arrowParens": "always",
"endOfLine": "lf"
}
5.3 EditorConfig
# .editorconfig
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2
[*.{py,cfg,ini}]
indent_size = 4
[Makefile]
indent_style = tab
[*.md]
trim_trailing_whitespace = false
5.4 Tailwind CSS + Vite 配置
// tailwind.config.ts
import type { Config } from "tailwindcss";
export default {
content: ["./src/**/*.{ts,tsx}", "./index.html"],
theme: {
extend: {
colors: {
primary: {
50: "#eff6ff",
100: "#dbeafe",
500: "#3b82f6",
600: "#2563eb",
700: "#1d4ed8",
},
accent: {
500: "#f59e0b",
},
},
fontFamily: {
sans: ["Inter", "system-ui", "sans-serif"],
},
animation: {
"fade-in": "fadeIn 0.3s ease-in-out",
},
keyframes: {
fadeIn: {
"0%": { opacity: "0" },
"100%": { opacity: "1" },
},
},
},
},
plugins: [require("@tailwindcss/typography")],
} satisfies Config;
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";
export default defineConfig({
plugins: [react(), tsconfigPaths()],
server: {
port: 3000,
proxy: {
"/api": {
target: "http://localhost:8000",
changeOrigin: true,
},
},
},
build: {
outDir: "dist",
sourcemap: false,
minify: "terser",
rollupOptions: {
output: {
manualChunks: {
vendor: ["react", "react-dom", "react-router-dom"],
},
},
},
},
});
5.5 Docker Compose 配置
# docker-compose.yml
version: "3.8"
services:
api:
build:
context: .
dockerfile: docker/Dockerfile
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/app
- REDIS_URL=redis://redis:6379/0
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
volumes:
- .:/app
- /app/.venv
restart: unless-stopped
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
POSTGRES_DB: app
ports:
- "5432:5432"
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user -d app"]
interval: 5s
timeout: 3s
retries: 5
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- redisdata:/data
volumes:
pgdata:
redisdata:
安全提醒：生成 .env.example 时，确保不包含真实的密钥和密码。Claude Code 不会也不应该在 .env 文件中写入敏感信息。生产环境的密钥应通过密钥管理服务（如 AWS Secrets Manager、Vault）分发。
六、Git 初始化
Git 初始化是项目脚手架中容易被忽视但至关重要的环节。Claude Code 可以自动完成从 .gitignore 创建到分支保护规则配置的全流程。
6.1 .gitignore 最佳实践
# .gitignore
# Python
__pycache__/
*.py[cod]
*.egg-info/
.venv/
.uv/
dist/
# Node
node_modules/
npm-debug.log*
.yarn/
# IDE
.idea/
.vscode/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
# Environment
.env
.env.local
.env.production
# Build
dist/
build/
*.tsbuildinfo
# Test
coverage/
.htmlcov/
.coverage
# Logs
*.log
logs/
6.2 Git 初始化完整命令序列
# 初始化仓库并进行初始提交
$ git init
$ git add .
$ git commit -m "chore: init project scaffold
- 配置 TypeScript + React + Vite 开发环境
- 集成 ESLint + Prettier 代码格式化工具
- 配置 Docker 容器化构建方案
- 添加 GitHub Actions CI 工作流"
# 连接远程仓库
$ git remote add origin https://github.com/username/project.git
$ git branch -M main
$ git push -u origin main
# 设置分支保护（需要 GitHub CLI）
$ gh repo edit --default-branch main
$ gh api repos/:owner/:repo/branches/main/protection \
--method PUT \
--field required_status_checks='{"strict":true,"contexts":["ci"]}' \
--field enforce_admins=true \
--field required_pull_request_reviews='{"required_approving_review_count":1}'
6.3 分支策略与命名规范
| 分支类型 | 命名模式 | 说明 |
|---|
| 主分支 | main | 生产就绪代码，受保护，禁止直接推送 |
| 开发分支 | develop | 集成分支，功能分支在此合并 |
| 功能分支 | feat/xxx | 新功能开发，如 feat/user-auth |
| 修复分支 | fix/xxx | Bug 修复，如 fix/login-error |
| 发布分支 | release/x.y.z | 发布准备，仅做 bug 修复和文档更新 |
| 热修复分支 | hotfix/xxx | 生产环境紧急修复 |
Git 初始化自动化：Claude Code 可以一次性完成所有 Git 初始化步骤 —— 创建 .gitignore、执行 git init、设置远程仓库、创建初始提交。只需要在 Prompt 中指定远程仓库地址即可。
七、CI 初始化
持续集成是现代软件工程的标配。Claude Code 可以在项目初始化时根据技术栈自动生成对应的 CI 配置文件。以下展示 GitHub Actions 的完整配置家族。
7.1 GitHub Actions 主 CI 工作流
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- uses: astral-sh/setup-uv@v3
- run: uv sync
- run: uv run ruff check .
- run: uv run mypy src/
test:
needs: lint
runs-on: ubuntu-latest
services:
postgres:
image: postgres:16-alpine
env:
POSTGRES_USER: app
POSTGRES_PASSWORD: app
POSTGRES_DB: app_test
ports:
- 5432:5432
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- uses: astral-sh/setup-uv@v3
- run: uv sync
- run: uv run pytest -v --cov=src --cov-report=xml --cov-report=term
- uses: codecov/codecov-action@v4
with:
file: ./coverage.xml
fail_ci_if_error: true
build:
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
with:
context: .
push: ${{ github.ref == 'refs/heads/main' }}
tags: ghcr.io/${{ github.repository }}:latest
cache-from: type=gha
cache-to: type=gha,mode=max
7.2 Dependabot 配置
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
day: "monday"
open-pull-requests-limit: 10
reviewers:
- "team-lead"
labels:
- "dependencies"
- "automated"
- package-ecosystem: "docker"
directory: "/"
schedule:
interval: "weekly"
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "monthly"
7.3 CodeQL 安全分析
# .github/workflows/codeql.yml
name: "CodeQL Security Scan"
on:
push:
branches: [main]
pull_request:
branches: [main]
schedule:
- cron: "0 6 * * 1" # 每周一早上 6 点
jobs:
analyze:
name: Analyze (${{ matrix.language }})
runs-on: ubuntu-latest
permissions:
security-events: write
packages: read
actions: read
contents: read
strategy:
fail-fast: false
matrix:
include:
- language: python
build-mode: none
- language: javascript-typescript
build-mode: none
steps:
- uses: actions/checkout@v4
- uses: github/codeql-action/init@v3
with:
languages: ${{ matrix.language }}
build-mode: ${{ matrix.build-mode }}
queries: security-and-quality
- uses: github/codeql-action/analyze@v3
with:
output: sarif-results
category: "/language:${{matrix.language}}"
7.4 Stale Bot 配置
# .github/workflows/stale.yml
name: "Stale Issue Manager"
on:
schedule:
- cron: "0 8 * * 1" # 每周一早上 8 点
jobs:
stale:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
steps:
- uses: actions/stale@v9
with:
stale-issue-message: >-
此 Issue 已 60 天无活动。请确认是否仍需处理，
否则将在 7 天后自动关闭。
stale-pr-message: >-
此 PR 已 30 天无活动。请更新代码或添加评论，
否则将在 7 天后自动关闭。
days-before-stale: 60
days-before-close: 7
days-before-pr-stale: 30
days-before-pr-close: 7
stale-issue-label: "stale"
stale-pr-label: "stale"
exempt-issue-labels: "pinned,security,enhancement"
exempt-pr-labels: "dependencies,security"
7.5 安全供应链配置（Scorecards）
# .github/workflows/scorecards.yml
name: OpenSSF Scorecards
on:
push:
branches: [main]
schedule:
- cron: "0 0 * * 0"
permissions: read-all
jobs:
analysis:
name: Scorecards analysis
runs-on: ubuntu-latest
permissions:
security-events: write
id-token: write
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: ossf/scorecard-action@v2
with:
results_file: results.sarif
results_format: sarif
publish_results: true
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
CI 配置策略建议：
① 不要在一开始配置过多工作流，会拖慢首次提交反馈；② 先配置核心 Lint + Test 管线；③ 随着项目成熟逐步添加安全扫描、部署等高级工作流；④ Claude Code 支持增量添加，可以在需要时快速补充配置。
八、端到端初始化 Prompt 示例
以下是一个完整的 Prompt 示例，展示了如何在一次对话中用 Claude Code 完成从零到项目骨架搭建的全流程：
// 在空目录中对 Claude Code 说：
"这是一个新的电商平台后端项目，请帮我完成完整的项目初始化：
## 技术栈
- Python 3.12 + FastAPI + SQLAlchemy 2.0 async + PostgreSQL 16
- Redis 缓存 + Celery 异步任务
- Docker 容器化 + Docker Compose 本地开发
- GitHub Actions CI + CodeQL 安全分析
## 项目结构要求
1. src/ 源码目录：按 domain 组织（auth/order/payment/product/user）
2. tests/ 测试目录：包含单元测试和 API 测试
3. alembic/ 数据库迁移目录
4. docker/ Docker 构建文件
5. scripts/ 开发工具脚本
6. docs/ 项目文档
## 需要生成的文件
1. 完整的项目目录结构和 __init__.py
2. pyproject.toml（含 ruff、mypy、pytest 配置）
3. CLAUDE.md（项目描述、技术栈、规范、命令别名）
4. Dockerfile + docker-compose.yml
5. .env.example + .gitignore
6. .github/workflows/ci.yml + codeql.yml + dependabot.yml
7. README.md 项目说明
8. alembic 初始迁移配置
9. src/main.py FastAPI 应用入口
10. src/core/config.py Pydantic Settings 配置类
请逐步执行以上任务，并在完成后验证项目可以正常构建。"
工作流效果：使用上述 Prompt，Claude Code 通常可以在 3-5 分钟内完成全部配置生成，生成 20-30 个文件，覆盖开发、构建、部署、安全的标准化配置，节省开发者半天到一天的手动配置时间。
九、核心要点总结
9.1 脚手架初始化最佳实践清单
| 阶段 | 检查项 | 优先级 |
|---|
| 项目模板 | 目录结构符合社区规范、文件命名一致、模块划分合理 | P0 |
| 框架脚手架 | 路由系统就绪、状态管理集成、中间件管线配置、错误处理覆盖 | P0 |
| CLAUDE.md | 技术栈记录完整、编码规范明确、命令别名可用、工作流规则清晰 | P0 |
| 配置文件 | TypeScript/ESLint/Prettier/EditorConfig 兼容、构建工具配置正确 | P1 |
| Git 初始化 | .gitignore 完整、初始提交可追溯、远程仓库配置正确 | P1 |
| CI 初始化 | 核心 CI 管线可运行、Lint + Test + Build 至少覆盖 | P1 |
| 安全配置 | Dependabot 启用、CodeQL 配置、Scorecards 配置（可选） | P2 |
9.2 常见陷阱与避坑指南
陷阱一：过度初始化 —— 一开始就配置所有 CI 工作流，导致项目尚未编写一行业务代码，CI 就已经失败多次。应遵循渐进式原则，先配核心管线。
陷阱二：忽略 CLAUDE.md 维护 —— 项目初始化后 CLAUDE.md 就再未更新，导致技术栈和目录结构文档与代码实际状态脱节。应养成每次引入新依赖或修改结构时同步更新的习惯。
陷阱三：配置文件之间不兼容 —— 例如 TypeScript strict 模式与某些库的类型定义冲突，或 ESLint 规则与 Prettier 冲突。Claude Code 生成配置时需明确指定兼容性要求。
9.3 Claude Code 初始化工作流的独特优势
- 上下文感知：Claude Code 会读取出项目已有文件（如 package.json），生成与之兼容的配置文件
- 自然语言驱动：无需记忆各种 CLI 工具的参数，用中文描述需求即可
- 可迭代优化：生成后可以通过对话调整细节，无需手动修改多文件
- 知识积累：通过 CLAUDE.md 记录项目知识，后续开发中保持一致性
- 跨技术栈统一：不管使用 React/Vue/Django/FastAPI/Express，工作流和交互方式一致
"好的开始是成功的一半。项目脚手架的质量决定了后续开发效率的上限。用 Claude Code 将重复的初始化工作自动化，让开发者将精力集中在真正创造价值的业务逻辑上。"