从立项到上线的标准流程

1总览：完整流程树状图

一张图看清楚从产品想法到生产环境之间发生了什么。每一个分叉代表团队的一次决策点。

2项目建立与初始化

2.1 在 GitLab 上创建项目

git clone git@gitlab.com:your-group/your-project.git
cd your-project
# 配置项目级 Git 身份（推荐）
git config user.name "Your Name"
git config user.email "you@company.com"

2.2 必备配置文件

2.3 权限模型

3敏捷节奏与任务管理

一个标准 Sprint（2 周）的时间轴：

3.1 GitLab Issue 作为最小工作单元

• 每个用户故事 → 一个 Epic（在 Premium 版）或 父 Issue
• 每个可在 1–2 天完成的任务 → 一个 Issue，打 ~feature / ~bug / ~chore label
• 用 Milestone 对齐 Sprint（如 Sprint-2026-W02），用 Iteration 跟踪燃尽
• 用 Issue Board（看板）可视化状态流转：Backlog → Ready → Doing → Review → Done

3.2 Issue 模板（团队约定）

## 背景
为什么要做？解决谁的什么问题？

## 验收标准 (Definition of Done)
- [ ] 功能 X 在场景 Y 下表现为 Z
- [ ] 单元测试覆盖 ≥ 80%
- [ ] 文档已更新

## 技术线索
建议涉及的模块、需要参考的 issue/MR

## Claude Code prompt（可选）
> 当此任务交给 Claude Code 时使用的初始指令

4分支策略与协作开发

推荐 GitLab Flow 简化版：长期分支 main（生产）+ develop（集成），短期分支 feature/* fix/* hotfix/*。

4.1 分支命名规范

4.2 Commit 规范（Conventional Commits）

feat(login): add OAuth2 google provider           # 新功能
fix(payment): handle stripe webhook timeout       # 修 bug
refactor(api): split user service                 # 重构
docs(readme): update local setup steps            # 文档
test(login): add edge case for empty password     # 测试
chore(deps): bump axios to 1.7.0                  # 杂项
ci(gitlab): cache pnpm store                      # CI

4.3 分支保护规则（Maintainer 设置）

• main：禁止直推、必须 MR、必须 CI 通过、必须至少 1 个 approval
• develop：禁止直推、必须 MR、CI 通过
• feature/* fix/*：开发者可直接 push

5Merge Request 与代码评审

MR 是协作的核心载体。它不是把代码丢过去就行——它是一次知识传递。

5.1 MR 描述模板

## 这个 MR 做了什么
一句话总结。

Closes #123

## 怎么验证
1. 拉这个分支
2. `pnpm dev`，访问 /login
3. 用账号 demo/123 登录，预期跳转到 /dashboard

## 截图 / 录屏
（UI 改动必须贴）

## Checklist
- [ ] 自测通过
- [ ] 加了单元测试
- [ ] 更新了文档
- [ ] 无 console.log 残留

5.2 评审重点（按优先级）

1. 逻辑正确性 — 真的解决了 issue 描述的问题吗？
2. 边界与错误处理 — 空值/超时/并发/权限
3. 安全 — SQL 注入、XSS、secret 泄露、越权
4. 可读性 — 命名、复杂度、注释
5. 性能 — N+1 查询、大对象、内存泄漏
6. 风格 — 交给 linter，不要在评审里争论

6Claude Code 工作流嵌入

把 Claude Code 当成一个高效但需要被评审的初级工程师。它不绕过任何流程，只是把每个环节做快。

6.1 CLAUDE.md：项目级"操作手册"

# 项目约定
- 技术栈: Next.js 15 + TypeScript + Prisma + PostgreSQL
- 测试: vitest + playwright，单测在 *.test.ts，e2e 在 /e2e
- 风格: 函数式优先，避免 class；早 return，少嵌套
- 提交: 遵循 conventional commits

# 禁止
- 不要直接改 prisma migration，要用 `pnpm db:migrate`
- 不要引入新依赖前先问
- 不要在生产代码留 console.log

# 常用命令
- 开发: `pnpm dev`
- 测试: `pnpm test`
- lint: `pnpm lint --fix`
- 类型检查: `pnpm typecheck`

6.2 推荐 Claude Code 使用范式

6.3 让 Claude Code 走完整流程的提示词样例

读 GitLab issue #234，理解需求后：
1. 先给我一个 5 步以内的实现计划，等我 ok
2. 从 develop 开一个分支 feature/234-user-export
3. 写代码 + 单元测试
4. 跑 `pnpm test` 和 `pnpm typecheck`，全绿再提
5. 写规范的 commit message，push 上去
6. 用 glab cli 发起 MR，描述里 Closes #234

每步完成报告一次，不要一口气干完。

7调试与缺陷管理

7.1 Bug 全流程

7.2 调试三板斧（与 Claude Code 配合）

7.3 Claude Code 调试提示词

这是一个生产 bug：用户点击「导出」按钮，500 报错。
错误日志：[贴 stack trace]
相关代码：src/api/export.ts
最近改动：MR !87

请：
1. 列出 3 个最可能的根因，按概率排序
2. 告诉我怎么本地复现
3. 写一个能稳定触发这个 bug 的失败测试
4. 不要直接改代码，等我确认根因再动手

8CI/CD 构建与部署

GitLab CI 用 .gitlab-ci.yml 定义流水线。每次 push / MR 自动触发。

8.1 极简版 .gitlab-ci.yml

stages: [verify, build, deploy]

default:
  image: node:22-alpine
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths: [node_modules/, .pnpm-store/]

install:
  stage: verify
  script:
    - corepack enable
    - pnpm install --frozen-lockfile

lint:
  stage: verify
  needs: [install]
  script: pnpm lint

typecheck:
  stage: verify
  needs: [install]
  script: pnpm typecheck

test:
  stage: verify
  needs: [install]
  script: pnpm test --coverage
  coverage: '/Lines\s*:\s*([\d.]+)%/'
  artifacts:
    reports:
      junit: junit.xml

build:
  stage: build
  needs: [lint, typecheck, test]
  script:
    - pnpm build
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  only: [develop, main, tags]

deploy_staging:
  stage: deploy
  needs: [build]
  script: kubectl set image deploy/app app=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -n staging
  environment: staging
  only: [develop]

deploy_prod:
  stage: deploy
  needs: [build]
  script: kubectl set image deploy/app app=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -n prod
  environment: production
  when: manual
  only: [tags]

8.2 Pipeline 设计原则

• 并行化：lint / typecheck / test 三个独立 job 同时跑，缩短 feedback 时间
• 失败快速：把最快的 job 放前面，比如 lint 30s 内能挂掉 → 不浪费后续算力
• 缓存依赖：node_modules、.pnpm-store、.next/cache 都缓存
• artifact 保留报告：测试报告、覆盖率、构建产物上传，便于追溯
• 生产部署手动 approve：自动到 staging，人工卡 prod

9发布与回滚

9.1 标准发布流程

git checkout develop && git pull
git checkout -b release/v1.2.0

git checkout main && git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

9.2 紧急回滚

# 方式一：重新部署上个 tag 的镜像（最快）
kubectl set image deploy/app app=$REGISTRY:v1.1.9 -n prod

# 方式二：revert commit 并走流程（更干净）
git checkout main
git revert 
git push        # 触发新 pipeline → 自动部署

10团队上手 Checklist