forked from Gitlink/gitlink-cli
323 lines
14 KiB
Markdown
323 lines
14 KiB
Markdown
---
|
||
name: gitlink-dev-full-cycle
|
||
description: "需求开发测试发布全流程。触发词：新需求开发、全流程推进、从需求到上线、启动需求、开发测试发布、feature全流程、需求落地、需求闭环、从0到1交付、从零开始开发、新建项目开发。6阶段：项目初始化→需求分析→技术设计→编码开发→测试验证→发布上线。集成gitlink-cli，分支三分支模型：master主分支/feature-xxx开发分支/release-xxx发布分支，每阶段输出标准文档。"
|
||
agent_created: true
|
||
---
|
||
|
||
# gitlink-dev-full-cycle — 需求开发测试发布全流程
|
||
|
||
## 触发词
|
||
|
||
新需求开发、全流程推进、从需求到上线、启动需求、开发测试发布、feature全流程、需求落地、需求闭环、从0到1交付、从零开始开发、新建项目开发
|
||
|
||
---
|
||
|
||
## ⚠ 核心规则：必须使用 gitlink-cli
|
||
|
||
本 Skill 与 GitLink 平台的所有交互**必须通过 `gitlink-cli` 命令完成**，禁止绕过 gitlink-cli 直接使用 GitLink Web 界面或 API。**禁止使用 `gitlink-cli api` 命令**（该命令用于发送原始 API 请求，容易误操作，所有操作应使用对应的专用子命令）。
|
||
|
||
### 🔴 执行 gitlink-cli 命令前，必须先查询 --help 确认正确格式！
|
||
|
||
gitlink-cli 的部分子命令使用 `+` 前缀（如 `+create`、`+merge`、`+run`），部分不需要（如 `auth status`、`auth login`）。**执行任何 gitlink-cli 命令前，必须先通过 `--help` 查询子命令列表，确认准确的命令格式后再执行。**
|
||
|
||
**查询方式：**
|
||
```bash
|
||
# 查看某模块下有哪些子命令（注意哪些带 + 哪些不带）
|
||
gitlink-cli repo --help
|
||
gitlink-cli branch --help
|
||
gitlink-cli pr --help
|
||
|
||
# 查看某子命令的详细参数
|
||
gitlink-cli repo +create --help
|
||
gitlink-cli pr +merge --help
|
||
```
|
||
|
||
**常见错误：AI agent 执行时丢掉 `+` 前缀，导致命令失败。**
|
||
```
|
||
❌ gitlink-cli repo create -n "项目名" # 丢掉了 +，会失败
|
||
✅ gitlink-cli repo +create -n "项目名" # 保留 +，正确
|
||
|
||
❌ gitlink-cli branch protect -n master # 丢掉了 +
|
||
✅ gitlink-cli branch +protect -n master # 保留 +
|
||
|
||
❌ gitlink-cli pr merge -i 123 # 丢掉了 +
|
||
✅ gitlink-cli pr +merge -i 123 # 保留 +
|
||
```
|
||
|
||
> **规则：不确定子命令格式时，先执行 `gitlink-cli <模块> --help` 查看可用子命令列表，照抄列表中的格式（含 `+` 或不含 `+`），禁止凭猜测省略或添加 `+`。**
|
||
|
||
**必须使用 gitlink-cli 的操作：**
|
||
- 创建代码仓库 → `gitlink-cli repo +create / +info`
|
||
- 创建/保护分支 → `gitlink-cli branch +create / +protect`
|
||
- 创建 PR / Review / 合并 → `gitlink-cli pr +create / +review / +merge`
|
||
- 触发流水线 / 查看构建 → `gitlink-cli pipeline +run / +runs`、`gitlink-cli ci +builds / +logs`
|
||
- 创建 Release → `gitlink-cli release +create`
|
||
- AI Code Review → `gitlink-cli workflow +pr-summary`
|
||
- 仓库健康检查 → `gitlink-cli workflow +health / +repo-report`
|
||
|
||
**本地 Git 操作使用原生 git：** `git add`、`git commit`、`git push`、`git pull`、`git checkout`、`git merge`、`git clone` 等。若 `git push` / `git pull` 需要认证，向用户询问账号密码或 Token，不使用 gitlink-cli auth。
|
||
|
||
---
|
||
|
||
## 分支策略
|
||
|
||
```
|
||
master ──────────────────────── 主分支（受保护，严禁直接提交或推送，存放最新稳定代码）
|
||
│ ↑
|
||
├──→ feature-xxx ──→（PR）──→ release-xxx ──→ 发版后合并回 master
|
||
│
|
||
└──→ feature-yyy ──→（PR）──→ release-zzz ──→ ...
|
||
```
|
||
|
||
**3 种分支说明：**
|
||
|
||
| 分支 | 命名规范 | 从哪拉 | 说明 |
|
||
|------|----------|--------|------|
|
||
| `master` | 固定 | — | 主分支，存放最新发布的稳定代码，**严禁直接提交代码或修改内容** |
|
||
| `release-xxx` | `release-<版本号或日期>` | `master` | 发布分支，用于版本发布准备，发版后保留所有版本，不删除 |
|
||
| `feature-xxx` | `feature-<功能描述>` | `master` | 开发分支，团队日常开发的基准分支，存放最新开发进度代码 |
|
||
|
||
**分支流转规则（严格遵守）：**
|
||
1. 每次开发时从 `master` 拉取 `feature-xxx` 分支进行功能开发和缺陷修复
|
||
2. 开发自测完成后，提交 PR 将 `feature-xxx` 合并到 `release-xxx`（发布分支）
|
||
3. 发版后将 `release-xxx` 合并回 `master` 分支
|
||
|
||
**禁止的行为：**
|
||
- ❌ 直接向 `master` 提交代码或 `git push origin master`
|
||
- ❌ `feature-xxx` 直接向 `master` 发 PR（必须先合入 `release-xxx`，再由 `release-xxx` 合回 `master`）
|
||
- ❌ 不同 `feature-xxx` 分支之间相互合并
|
||
|
||
---
|
||
|
||
## 前置步骤：认证检查
|
||
|
||
在执行任何阶段之前，**必须先确认 gitlink-cli 认证状态**：
|
||
|
||
```bash
|
||
gitlink-cli auth status # 检查认证状态
|
||
```
|
||
|
||
- 若已认证 → 继续执行阶段零
|
||
- 若未认证 → 执行 `gitlink-cli auth login` 登录，登录成功后再继续
|
||
|
||
---
|
||
|
||
## ⚠ 阶段零：项目初始化（必须第一个执行！）
|
||
|
||
> **本阶段是后续所有阶段的前提，必须第一个完成！未完成阶段零，禁止进入阶段一及后续任何阶段。** 只有当项目已有远程仓库且本地已克隆时，才可跳过本阶段（需向用户确认）。
|
||
|
||
1. 确认项目信息：仓库名、owner、公开/私有、技术栈
|
||
|
||
2. **先在 GitLink 远程创建仓库：**
|
||
|
||
```bash
|
||
gitlink-cli repo +create -n "项目名" -d "描述" --private "true"
|
||
gitlink-cli repo +info --owner "org" --repo "项目名" # 确认远程仓库创建成功
|
||
```
|
||
|
||
3. **再克隆到本地并初始化项目骨架：**
|
||
|
||
```bash
|
||
git clone <仓库URL> && cd <项目名>
|
||
# 按技术栈初始化项目骨架（vite / fastapi / express / go mod init ...）
|
||
git add . && git commit -m "init" && git push origin master
|
||
```
|
||
|
||
4. **保护 master 分支（严禁直接推送）：**
|
||
|
||
```bash
|
||
gitlink-cli branch +protect --owner "org" --repo "项目名" -n master
|
||
gitlink-cli workflow +health --owner "org" --repo "项目名"
|
||
```
|
||
|
||
5. **输出文档：** 项目根目录下写入以下基础文档：
|
||
- `README.md` — 项目简介、技术栈、本地开发启动步骤、目录结构说明
|
||
- `.gitignore` — 根据技术栈生成标准忽略规则
|
||
- `docs/` 目录 — 创建文档目录，后续各阶段文档统一存放于此
|
||
|
||
---
|
||
|
||
## 阶段一：需求分析
|
||
|
||
1. 向用户确认：需求背景、核心功能点、验收标准（AC）、优先级
|
||
2. 输出结构化需求：用户故事 + 功能清单 + AC（Given/When/Then）+ Out-of-scope
|
||
3. **输出文档 `docs/requirements.md`：** 按模板写入完整需求文档（含背景、目标用户、用户故事、功能清单、验收标准、Out-of-scope、依赖与风险）
|
||
4. 用户确认需求文档后进入下一阶段
|
||
|
||
---
|
||
|
||
## 阶段二：技术设计
|
||
|
||
1. 分析技术选型：技术栈、数据模型、接口契约、第三方集成
|
||
2. 识别风险与难点，给出解法
|
||
3. **输出文档 `docs/design.md`：** 按模板写入完整设计文档（含技术栈选型表、系统架构图、数据模型DDL、接口契约、关键实现思路、风险与缓解措施）
|
||
4. 用户确认设计文档后进入下一阶段
|
||
|
||
---
|
||
|
||
## 阶段三：编码开发
|
||
|
||
1. **从 master 创建 feature 开发分支：**
|
||
|
||
```bash
|
||
gitlink-cli branch +create -n "feature-<功能描述>" -f master
|
||
git fetch origin && git checkout feature-<功能描述>
|
||
```
|
||
|
||
2. 用 TaskCreate 拆分开发子任务，逐任务实现（先 Happy Path 再边界）
|
||
3. 遵守编码规范：函数职责单一、关键逻辑注释、无硬编码、类型注解
|
||
4. **输出文档：**
|
||
- **代码注释** — 公共函数/类必须有 docstring 或 JSDoc，说明用途、参数、返回值
|
||
- **`docs/api.md`**（如有 HTTP API）— 列出所有新增接口的路径、方法、参数、响应、错误码
|
||
- **配置文件说明** — 新增配置项需在文档中注明用途和默认值
|
||
5. 完成后提交推送：
|
||
|
||
```bash
|
||
git add . && git commit -m "feat: XXX" && git push origin feature-<功能描述>
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段四：测试验证
|
||
|
||
### 单元测试 + Lint
|
||
编写单元测试覆盖核心逻辑、边界、异常；运行 Lint 修复 Error。
|
||
|
||
### 创建发布分支（release-xxx）并集成 feature
|
||
|
||
```bash
|
||
# 若 release-xxx 尚未存在，从 master 创建
|
||
gitlink-cli branch +create -n "release-<版本号>" -f master
|
||
# 将 feature 分支合并到 release 分支
|
||
git checkout release-<版本号> && git merge feature-<功能描述> && git push origin release-<版本号>
|
||
```
|
||
|
||
### 触发流水线，验证集成结果
|
||
|
||
```bash
|
||
gitlink-cli pipeline +run -w <ci-workflow> -r release-<版本号>
|
||
gitlink-cli pipeline +runs -r release-<版本号> # 查看运行状态
|
||
gitlink-cli ci +builds && gitlink-cli ci +logs # 查看构建详情
|
||
```
|
||
|
||
冒烟测试：逐条验证 AC。
|
||
|
||
### Code Review（PR: feature-xxx → release-xxx）
|
||
|
||
```bash
|
||
gitlink-cli pr +create -t "feat: XXX" --head "feature-<功能描述>" --base "release-<版本号>"
|
||
gitlink-cli workflow +pr-summary -n <pr-number> # AI Review
|
||
gitlink-cli pr +diff -i <pr-number>
|
||
gitlink-cli pr +review -i <pr-number> -s approved -c "LGTM"
|
||
gitlink-cli pr +merge -i <pr-number> -m merge
|
||
```
|
||
|
||
### **输出文档 `docs/test-report.md`：**
|
||
按模板写入测试报告（含测试范围、测试环境、AC逐条验证结果、单元测试覆盖率、遗留问题清单）
|
||
|
||
---
|
||
|
||
## ⚠ 阶段五：发布上线（必须严格按顺序执行，禁止跳步！）
|
||
|
||
> **🔴 发布上线阶段的所有步骤必须严格按下方顺序逐步执行，禁止跳过任何步骤、禁止调换顺序、禁止自行发明其他发布方式。**
|
||
>
|
||
> **禁止的行为：**
|
||
> - ❌ feature-xxx 直接向 master 发 PR（必须经过 release-xxx）
|
||
> - ❌ 未经用户确认就触发生产流水线或执行 release-xxx 合并回 master
|
||
> - ❌ 直接 `git push origin master`（master 受保护，只能通过 PR 合入）
|
||
> - ❌ 合并 PR 后不创建 Release
|
||
> - ❌ 用 `git merge` 直接操作 master 绕过 PR 流程
|
||
|
||
### 第 1 步：发布前确认（全部满足才能继续）
|
||
|
||
- [ ] 所有测试通过
|
||
- [ ] PR Review 通过（feature-xxx 已合并到 release-xxx）
|
||
- [ ] 配置已更新
|
||
- [ ] 回滚方案已确认
|
||
- [ ] **用户明确确认"可以发布"**
|
||
|
||
### 第 2 步：触发生产流水线，执行发布
|
||
|
||
```bash
|
||
gitlink-cli pipeline +run -w <prod-workflow> -r release-<版本号> # ⚠ 需用户确认
|
||
gitlink-cli ci +builds && gitlink-cli ci +logs # 监控构建
|
||
```
|
||
|
||
生产冒烟验证 + 监控指标检查。
|
||
|
||
### 第 3 步：release-xxx 合并回 master（⚠ 不可逆，需用户确认）
|
||
|
||
```bash
|
||
gitlink-cli pr +create -t "release-<版本号> 合并回 master" --head "release-<版本号>" --base "master"
|
||
gitlink-cli pr +merge -i <pr-number> -m merge # ⚠ 需用户确认
|
||
```
|
||
|
||
> **保留所有 release-xxx 分支，不删除。**
|
||
|
||
### 第 4 步：输出文档
|
||
|
||
- **`CHANGELOG.md`** — 在文件顶部追加本次版本条目（Added / Changed / Fixed / Breaking Changes）
|
||
- **`docs/release-notes.md`** — 按模板写入发布通知（版本号、上线时间、更新内容、验证方式、回滚方案）
|
||
|
||
### 第 5 步：创建 Release
|
||
|
||
```bash
|
||
gitlink-cli release +create -t "v1.x.0" -n "v1.x.0-需求名" --target master --prerelease false
|
||
```
|
||
|
||
> **所有 feature-xxx 和 release-xxx 分支均保留，不删除。**
|
||
|
||
---
|
||
|
||
## 文档清单总览
|
||
|
||
| 阶段 | 输出文档 | 存放位置 |
|
||
|------|----------|----------|
|
||
| 阶段零 | README.md、.gitignore | 项目根目录 |
|
||
| 阶段一 | requirements.md | `docs/` |
|
||
| 阶段二 | design.md | `docs/` |
|
||
| 阶段三 | api.md（如有API）、代码注释 | `docs/` + 源码 |
|
||
| 阶段四 | test-report.md | `docs/` |
|
||
| 阶段五 | CHANGELOG.md、release-notes.md | 项目根目录 + `docs/` |
|
||
|
||
> 所有文档模板见 `references/templates.md`，按模板格式写入，确保结构统一。
|
||
|
||
---
|
||
|
||
## 进度追踪
|
||
|
||
执行时用 TaskCreate 建立任务列表：
|
||
|
||
```
|
||
[ ] 阶段零：项目初始化 → README.md + .gitignore
|
||
[ ] 阶段一：需求分析 → docs/requirements.md
|
||
[ ] 阶段二：技术设计 → docs/design.md
|
||
[ ] 阶段三：编码开发 → feature-xxx 分支 + api.md + 代码注释
|
||
[ ] 阶段四：测试验证 → docs/test-report.md + PR Review（feature-xxx → release-xxx）
|
||
[ ] 阶段五：发布上线 → CHANGELOG.md + release-notes.md + release-xxx合并回master + Release
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
- **阶段零必须第一个执行，未完成禁止进入后续阶段**（已有仓库需用户确认后方可跳过）
|
||
- 小需求可裁剪阶段一至五，但阶段零不可裁剪
|
||
- **所有平台操作必须使用 `gitlink-cli`，禁止绕过直接使用 Web 界面或 API**
|
||
- **禁止使用 `gitlink-cli api` 命令**（原始 API 请求易误操作，应使用对应的专用子命令）
|
||
- **执行 gitlink-cli 命令前，先通过 `--help` 查询确认子命令格式（部分子命令有 `+` 前缀，部分没有），禁止凭猜测省略或添加 `+`**
|
||
- **分支规则：feature-xxx 从 master 拉；开发完 PR 合到 release-xxx；发版后 release-xxx 合回 master；master 严禁直接提交**
|
||
- **发布上线阶段必须严格按照第1步→第5步顺序执行，禁止跳步、禁止调换顺序、禁止自行发明其他发布方式**
|
||
- 不可逆操作（release-xxx 合并回 master、触发生产流水线）执行前必须获得用户确认
|
||
- `git push` / `git pull` 需认证时向用户询问，不使用 gitlink-cli auth
|
||
- 每阶段输出文档后才算阶段完成，文档需用户确认后才能推进
|
||
- `--owner` / `--repo` 在 Git 仓库目录下可自动探测
|
||
- 项目已有规范时优先遵循，不覆盖
|
||
|
||
---
|
||
|
||
## 参考资源
|
||
|
||
- `references/checklist.md` — 各阶段检查清单
|
||
- `references/templates.md` — 需求文档、设计文档、测试报告、Changelog 等模板
|