name: gitcode-dev-workflow description: | 通用 AI 开发工作流的详细 playbook：覆盖 Phase 0-5（上下文加载 → Issue → 轻量设计 → AI 编码 → 用户自测反馈环 → 业务 PR → 用户触发归档），按 Light / Standard / Full 三模式给出具体执行清单、闸门证据、Artifact 模板、独立触发能力的调用时机，以及 Superpowers 与 gitcode skills 的串联映射。
TRIGGER when: 用户要开始一个新需求、启动开发工作流、走完整工程流程、 或说 "start workflow"、"开始开发"、"新功能开发"、"完整流程"、"从需求到交付"、 "走一遍全流程"。当用户有模糊想法但不知道从哪步开始时，这应该是第一个触发的 skill。 本 skill 也是 AGENTS.md "🚨 开发工作流分级规则" 的详细操作展开—— AGENTS.md 定约束，本 skill 给操作。
通用 AI 开发工作流（详细 playbook）
本 skill 与 AGENTS.md 的关系
| 文件 | 加载方式 | 内容定位 |
|---|---|---|
AGENTS.md |
项目级 system prompt，每次会话都加载 | 核心约束、必须遵守的规则、模式判定、闸门简表 |
gitcode-dev-workflow（本 skill） |
按需触发 | 详细操作步骤、各模式的执行清单、模板、独立能力调用时机 |
优先级：当本 skill 与 AGENTS.md 冲突时，以 AGENTS.md 为准。本 skill 只是把 AGENTS.md 的约束展开成可执行步骤。
前提
- 运行环境：Windows + Trae（或其他支持
AGENTS.md/.agents/skills/的 AI 开发环境），技能目录.agents/skills/。 - GitCode CLI：始终使用
gitcode命令；gc是 PowerShell 内置Get-Content别名，会冲突。 - 凭证：依赖 Windows 用户级永久环境变量
GC_TOKEN，由初始化 Playbook 配置。 - 多仓工作区：
<repo-name>/（业务仓）+specs/（spec/issue/release 文档仓）+.agents/skills/（项目级 skill）。
流程总览
Phase 0 Phase 1 Phase 2 Phase 3 [用户自测/反馈环] Phase 4 Phase 5
上下文加载 → Issue 与需求确认 → 轻量设计与计划 → AI 编码交付 → 用户测试 → 修改 → 业务 PR 交付 → 最终归档
(循环直到用户确认完成) (用户明确触发)
关键卡点：
- 模式（Light / Standard / Full）在 Phase 0 末就要确定，未确认前不动代码。
- Phase 4 业务 PR 只能在用户明确表示自测完成后创建，不要替用户拍板。
- Phase 5 归档只能由用户触发，AI 不主动归档。
模式选择
完整判定表见 AGENTS.md 的"流程模式判定"小节。本 skill 提供与用户对话的具体动作：
选择策略
- 用户明确指定模式 → 直接采用，不再判定。
- 用户没指定 → AI 必须先评估再向用户提议：
- 改动规模（行数）、仓库范围（单仓/跨仓）、接口/数据/安全/部署影响、测试要求、文档要求
- 给出推荐模式 + 判定依据 + 会执行/跳过哪些环节
- 拿到用户确认后才进入 Phase 1
与用户确认的标准模板
基于你的需求，我推荐 [Light / Standard / Full] 模式：
- 改动规模：约 N 行，涉及 <文件/模块>
- 关键判断点：<接口/数据/安全/部署>
- 将执行：<列出会做的事>
- 将跳过：<列出会跳过的事，对应模式分级表中标"跳过"或"可选"项>
是否按此模式进行？或者你想升/降级？
模式判定边界情形
| 情形 | 建议 |
|---|---|
| 改动看似 30 行内但触及鉴权/数据/外部接口 | 升级到 Standard 或 Full（安全/接口变化优先于行数） |
| Standard 范围但用户明确要求快速验证一个想法 | 可暂时按 Light 推进，但要明确告诉用户跳过了哪些保障 |
| Full 范围但跨仓影响仅是文档链接更新 | 业务仓走 Standard，specs 仓单独按需走简化流程 |
| 无法估算改动规模 | 默认 Full，开题用 brainstorming skill 把范围拆出来 |
Phase 0 — 上下文加载
目标
向用户输出"我知道改哪个仓、看了哪些文档、推荐什么模式"，避免无差别全量扫描工作区。
步骤
-
识别目标仓
<repo-name>与需求范围- 从用户请求中提取仓名；不确定就直接问。
- 跨仓需求：明确受影响仓集合后再分别按下面 4 项展开。
-
按模式加载默认上下文：
模式 必读 选读（按需检索） Light 目标文件本身 + 仓库 README/规则 用户指定的材料 Standard <repo-name>/+specs/spec/<repo-name>/ai_memory.mdsystem_design/、task_design/<需求目录>/、specs/issue_docs/<repo-name>/、specs/release_docs/<repo-name>/（按关键词rg检索）Full 上述全部 + specs/architecture_design/specs/test_docs/、跨仓影响的其他仓 spec/issue -
检索策略：
- 优先用
rg "<keyword>" <target-dir>，不要cat整个文件。 - 先看 README/索引/设计/任务文档，再看源码细节。
- 不要把
specs当业务代码仓改。
- 优先用
-
分支检查（强制）：
git -C <repo-name> branch --show-current- 若在
master/main，立即停止并要求用户切到或新建特性分支：# 业务仓 git checkout -b feat/<description> # 或 fix/<description> # specs 仓 git checkout -b spec/<repo-name>/<change-name>
- 若在
🔒 闸门：Phase 0 → Phase 1
向用户输出：
- 已识别目标仓：
<repo-name> - 当前分支：
<branch>（必须不是 master/main） - 已加载的关键上下文：列出 3-5 个最相关的文档/文件
- 推荐流程模式：
<Light/Standard/Full>+ 判定依据 + 会执行/跳过的关键环节 - 等待用户确认
Phase 1 — Issue 与需求确认
目标
产出"业务 Issue URL + 用户确认的需求范围"。所有业务 PR 必须关联 Issue。
步骤
-
创建或关联业务 Issue
- 现成 Issue：拿到编号后用
gitcode issue view <n>核对范围。 - 没有现成 Issue：通过
gitcode-issue-createskill 或直接 CLI 创建。 - 含中文内容必须用
--body-file+ UTF-8 写盘（见后文 Windows 编码小节）。
- 现成 Issue：拿到编号后用
-
需求澄清（按模式深度调整）：
模式 澄清深度 Light 需求明确时一句确认即可：「我理解是要改 X，预期行为 Y，对吗？」 Standard 简化澄清：做什么 / 不做什么 / 验收标准 Full 完整澄清，必要时调用 brainstormingskill，至少问清：为谁解决什么 / 验收标准 / 边界 / 参考方案 -
生成需求记录（按模式落盘）：
模式 产出 位置 Light Issue/PR 描述承载即可，不强制落盘 — Standard 简版 proposal.md，必要时简版tasks.mdspecs/spec/<repo-name>/task_design/<change-name>/Full proposal.md+design.md+tasks.md同上 Artifact 文件位置：所有 spec 文件落到
specs仓，不要放在业务仓里（业务仓 PR 不允许带 spec 文件）。 -
跨仓引用规范：
- Issue/PR body 中跨仓引用用
<owner>/<repo>#<n>语法。 - 引用 spec 文件用 GitCode permalink（commit SHA URL），避免分支删除后失效：
https://gitcode.com/<owner>/specs/blob/<commit-sha>/spec/<repo>/task_design/<change-name>/proposal.md
- Issue/PR body 中跨仓引用用
🔒 闸门：Phase 1 → Phase 2
向用户出示：
- 业务 Issue URL
- 用户确认的需求范围（做什么 / 不做什么 / 验收标准）
- （Standard / Full）proposal.md / design.md 草稿路径
- 等待用户确认
Phase 2 — 轻量设计与计划
目标
产出"实现计划 + 生成前约束清单"，让用户确认 AI 接下来要改的范围和方式。
步骤
-
生成前约束检查（强制，所有模式）：把代码审查要求前置为编码必须遵守的规范，至少包括：
- 只修改用户指定业务仓 + 允许的
specs范围 - 遵循目标仓既有架构、命名、错误处理、日志、配置、测试风格
- 避免无关重构、无关格式化、元数据 churn
- 无硬编码凭证、敏感信息、危险默认值或明显注入风险
- 行为变化必须有匹配的测试或说明不可测原因
- 只修改用户指定业务仓 + 允许的
-
按模式确认实现计划：
模式 计划深度 Light 一句话说明将修改的文件 + 最小验证方式 Standard 列出任务 checklist（涉及文件 + 测试方式），可不写完整 design.md Full 调用 writing-plansskill 拆 2-5min 原子任务；写完整 design.md（含影响范围/关键决策）+ tasks.md -
TDD 计划（按模式）：
模式 要求 Full 有行为变化时优先 RED → GREEN → REFACTOR，并执行完整测试策略 Standard 有行为变化时必须补充或更新相关测试，并运行相关验证 Light 有行为变化且可测时补充最小测试；文案/注释/无行为配置改动可说明原因后跳过
🔒 闸门：Phase 2 → Phase 3
向用户出示：
- 实现计划（修改文件清单 + 验证方式）
- 生成前约束清单
- （Standard / Full）tasks.md 路径
- 等待用户确认
Phase 3 — AI 编码交付
目标
产出"本轮 AI 编码交付的 commit + 验证结果"。这一轮是 AI 写代码、跑验证、提交 commit，还没到业务 PR。
步骤
-
按计划修改代码
- 严格按 Phase 2 的实现计划改，不要做计划外的重构或格式化。
- 行为变化优先补充/更新测试；无可测行为变化时在 commit body 或交付说明里写清原因。
-
运行匹配模式的必要验证：
模式 验证范围 Light 最小相关验证（编译 + 改动文件的测试） Standard 相关测试 + 构建 Full 完整测试策略要求的验证 质量门禁完整套件（format/static/coverage 等）不是主流程强制项，需要时通过
gitcode-dev-qualityskill 独立触发。具体命令由业务仓 AGENTS.md 的"质量门禁命令"小节填充。 -
AI 交付自检：对照 Phase 2 的生成前约束清单逐条勾选；不符合的立即修复。
-
提交 commit（强制，每轮一次）：
- 粒度：一轮 AI 编码交付 = 一次 commit，不是每个原子任务一个 commit。
- 用户自测反馈后的每轮修改也必须提交新 commit。
- 格式见后文"Commit 规范详解"。
🔒 闸门：Phase 3 → 用户自测
向用户出示：
- 本轮 commit hash + commit message 摘要
- 验证结果（哪些测试跑了、是否通过）
- AI 自检清单结果
- 明确告诉用户："请自测，发现问题继续告诉我，确认完成后我再创建业务 PR。"
用户自测 / 反馈循环
行为约定
- 不要替用户拍板"完成"。即使所有测试通过，没有用户明确确认前，不要进入 Phase 4。
- 用户反馈问题 → AI 回到 Phase 3 修改 → 跑必要验证 → 提交新 commit → 再次交还用户。
- 每轮修改都是独立 commit，不要 amend 之前的 commit。
- 这个循环可能跑多轮，每轮 commit 都引用业务 Issue（
Refs #<n>）。
用户表达"完成"的信号
- 明确说"完成了 / 可以提 PR 了 / 没问题了"
- 明确要求"开始 Phase 4 / 创建 PR"
模糊信号（如"看起来不错"）不算确认，要追问一句"是否进入 Phase 4 创建业务 PR？"。
Phase 4 — 业务 PR 交付
目标
产出"业务 PR URL"。PR 关联业务 Issue，打 ai-assisted 标签。
步骤
-
确认进入条件：用户已明确表示自测/反馈循环完成。
-
创建或更新 PR：
- 业务仓发起 PR 到
main/master。 - 关联 Issue：PR body 写
Refs #<n>或Fixes #<n>。 - 必须加
ai-assisted标签（该标签已预先创建，不要重复创建）。 - 中文 PR 描述：
gitcode pr create已支持--body-file，可直接一步创建；但--labels不支持，需创建后用gitcode pr edit --labels ai-assisted补打。
- 业务仓发起 PR 到
-
PR 描述写清（按模式调整完整度）：
模式 PR 描述要点 Light 变更内容 + 关联 Issue + AI 参与说明 Standard 上述 + 验证结果摘要 Full 上述 + 关键决策、风险与缓解、跨仓影响 -
可选独立能力：
- 用户要求看 CI / PR 卡在流水线 →
gitcode-pipeline-analyzer - 用户要求 code review →
gitcode-pr-review - 用户要求质量门禁报告 →
gitcode-dev-quality - 用户要求安全审查 →
gitcode-security-check
这些都不是 Phase 4 的强制卡点，只在用户要求时触发。
- 用户要求看 CI / PR 卡在流水线 →
🔒 闸门：Phase 4 完成
向用户出示：
- 业务 PR URL
- PR 标签包含
ai-assisted - PR 关联的 Issue 编号
- 此时不要主动进入 Phase 5，等用户触发。
Phase 5 — 最终归档（用户明确触发）
触发条件
只有用户明确说"归档 / Phase 5 / 沉淀经验"才执行。业务 PR 完成或合入后，AI 不主动归档。
步骤
-
汇总归档信息：
- 业务 Issue URL、业务 PR URL
- 每轮 AI 编码交付 commit hash + 简短说明
- 用户自测/反馈循环中发现的问题和修复结论
- 最终验证结果
- 设计偏差、实现取舍
-
生成 archive.md：落到
specs/spec/<repo-name>/task_design/<change-name>/archive.md。模板见下文。 -
沉淀 ai_memory.md（仅在确实有可复用经验时）：
- 只沉淀经过验证且未来会复用的规则。
- 不要把一次性的实现细节塞进 ai_memory。
- 路径：
specs/spec/<repo-name>/ai_memory.md。
-
提交 specs PR：
- 分支：
spec/<repo-name>/<change-name> - PR 标题：
docs(spec/<repo-name>): <change-name> - PR 描述：关联业务仓 issue（
<owner>/<repo>#<n>）+ 变更摘要 - 必须加
ai-assisted标签 - 必须通过 PR 合入，不允许直接 push 到 specs 仓的 master/main
- 分支：
-
证据链使用 permalink：archive.md 中引用的 commit / spec / PR 链接都用 GitCode permalink（commit SHA URL）。
🔒 闸门：Phase 5 完成
- archive.md 已合入 specs 仓
- 如有 ai_memory.md 更新，已合入 specs 仓
- 业务 Issue 状态正确（关闭 or 标记完成）
Artifact 模板
proposal.md
# <Change Name>
## 需求背景
[为什么需要这个变更]
## 功能描述
[做什么，不做什么]
## 验收标准
- [ ] 标准 1
- [ ] 标准 2
## 影响范围
[受影响的模块/文件/仓]
Light 模式极简版（3 行即可）：
# <change-name>
## 需求
一句话描述要改什么。
## 验收
- [ ] 预期行为
design.md
# <Change Name> — 技术设计
## 方案概述
[技术方案一句话描述]
## 架构决策
[关键决策及原因]
## 涉及文件
| 文件 | 操作 | 说明 |
|------|------|------|
| path/to/File | 新增/修改 | [说明] |
## 风险 & 缓解
[已知风险和应对]
## 跨仓影响
[如有，列出受影响仓和具体接口/契约]
无新决策时可省略，或写一行"无新增技术决策，直接修改 <file>"。
tasks.md
# <Change Name> — 实现任务
## 进度: N/M complete
- [ ] Task 1: <描述>
- [ ] Task 2: <描述>
- [ ] Task 3: <描述>
Light 模式 1 条 checkbox 即可。
archive.md
# <Change Name> — 归档
## 关联
- 业务 Issue: <permalink>
- 业务 PR: <permalink>
- specs PR: <permalink>
## 交付历程
- commit `<sha>`: <一句话说明>
- commit `<sha>`: <一句话说明>
## 用户自测反馈
- 发现问题：<描述> → 修复 commit `<sha>`
## 最终验证
- <验证项>：<结果>
## 设计偏差与取舍
- <如有>
## 可复用经验
- <如有，同步到 ai_memory.md>
## 归档日期
YYYY-MM-DD
独立触发能力
以下能力不属于主开发流程强制卡点，按用户要求或任务明确需要时触发：
| 能力 | Skill | 典型触发场景 |
|---|---|---|
| 质量检查 | gitcode-dev-quality |
用户要求"质量检查 / 提交前检查 / lint / 覆盖率"；准备发版前；CI 失败定位 |
| 安全审查 | gitcode-security-check |
用户要求安全审查；改动涉及鉴权/输入/凭证/依赖 |
| PR 审查 | gitcode-pr-review |
用户要求审 PR / 代码评审；merge 前最后一道 review |
| 流水线分析 | gitcode-pipeline-analyzer |
用户要求看流水线 / CI 失败 / 耗时分析 |
| 发布 | gitcode-release-helper |
用户要求发版；准备 release note |
| Issue 分类 | gitcode-issue-triage |
存量 Issue 运营（与单需求开发无关） |
| 仓库 onboarding | gitcode-repo-onboarding |
新人首次接触某仓时（与单需求开发无关） |
与 Superpowers / gitcode skills 的协同
主线工作流 skill：
| Phase | Superpowers | gitcode skills |
|---|---|---|
| Phase 0 | — | — |
| Phase 1 | brainstorming（Full 模式建议触发） |
gitcode-issue-create, gitcode-issue-review |
| Phase 2 | writing-plans（Full）、test-driven-development（按模式）、subagent-driven-development（仅在多个独立任务时） |
— |
| Phase 3 | requesting-code-review（可选，每轮交付前自检） |
— |
| Phase 4 | finishing-a-development-branch（merge 决策辅助） |
gitcode-pipeline-analyzer、gitcode-pr-review（按需）、gitcode-release-helper（按需） |
| Phase 5 | — | — |
子代理使用规则
- 不再按每个原子任务强制启动子代理。
- 仅在用户授权 + 任务可拆成多个互不冲突的独立工作项时使用。
- 启动时必须传入当前分支名，子代理不得切换分支。
- 必须明确写入范围，子代理不得修改超出任务描述的文件。
- 组名建议：
workflow-<task-id>。
Commit 规范详解
格式
<type>(<scope>): <summary in present tense, ≤72 chars>
<body: what changed and why, reference issues if applicable>
Co-authored-by: <Tool / Agent Name> <noreply@tool-provider.com>
Generated-by: <underlying-model-id>
字段约束
| 字段 | 约束 |
|---|---|
<type> |
feat / fix / docs / refactor / test / chore / perf / build / ci |
<scope> |
模块名 / 包名 / 子系统（如 auth、core；specs 仓用 spec/<repo-name>） |
| summary | 现在时祈使式，≤72 字符，不以句号结尾 |
| body | 改了什么 + 为什么；关联 issue 用 Refs #<n> 或 Fixes #<n>；body 与 trailers 之间空 1 行 |
Co-authored-by |
AI 工具名 + provider 邮箱：Trae <noreply@trae.ai>、Claude Code <noreply@anthropic.com>、Cursor <noreply@cursor.com> |
Generated-by |
底层模型 ID：claude-opus-4-7、claude-sonnet-4-6、gpt-5-codex |
示例
feat(core): add batch processing support for data pipeline
添加数据管道批量处理能力，解决单条处理吞吐量不足问题。
Refs #42
Co-authored-by: Trae <noreply@trae.ai>
Generated-by: claude-opus-4-7
常见错误
- ❌ 把多轮 AI 交付塞到一个 commit 里（应该一轮一 commit）
- ❌ 用户反馈后
git commit --amend（应该新 commit） - ❌ summary 写过去式或带句号
- ❌ 忘记
Refs #<n>关联 Issue - ❌ 忘记
Generated-by（审计追踪必需）
GitCode CLI 常用命令
| 操作 | 命令 |
|---|---|
| 创建 Issue | gitcode issue create -R <owner/repo> --title <t> --body-file <f> --label <labels> |
| 评论 Issue | gitcode issue comment <n> -R <owner/repo> --body-file <f> |
| 关闭 Issue | gitcode issue edit <n> -R <owner/repo> --state close |
| 查询 Issue | gitcode issue view <n> / gitcode issue list |
| 创建 PR | gitcode pr create -R <owner/repo> --title <t> --body-file <f> --base <branch> |
| PR 补打标签 | gitcode pr edit <n> -R <owner/repo> --labels ai-assisted |
| 编辑 PR body（中文） | gitcode pr edit <n> -R <owner/repo> --body-file <f> |
| 评论 PR | gitcode pr comment <n> -R <owner/repo> --body-file <f> |
| PR 行内评论 | gitcode pr comment <n> -R <owner/repo> --body <text> --path <file> --position <n> |
| PR 审查 | gitcode pr review <n> -R <owner/repo> --approve --comment-file <f> |
| 查询 PR | gitcode pr view <n> / gitcode pr list |
| 合并 PR | gitcode pr merge <n> -R <owner/repo> --method <merge/squash/rebase> --yes |
| 编辑 issue 评论 | gitcode issue comment edit <id> --body-file <f> |
跨仓引用：issue/PR body 中用 <owner>/<repo>#<n> 语法。
凭证：依赖 Windows 用户级永久环境变量 GC_TOKEN。若 gitcode auth status 报未登录，立即停止并要求用户重新提供 token，禁止自行猜测或绕过。
Windows 中文编码（强制踩坑预防）
PowerShell 默认编码与 UTF-8 不一致，直接用 --body 传中文会让远端显示乱码。所有含中文的远端写操作都必须用 --body-file + 显式 UTF-8 写盘。
正确做法
[System.IO.File]::WriteAllText("$env:TEMP\comment.md", $bodyContent, [System.Text.Encoding]::UTF8)
gitcode issue comment <n> --body-file "$env:TEMP\comment.md"
错误做法
# ❌ 直接用 --body 传中文变量
gitcode issue comment <n> --body $bodyContent
# ❌ 用 Get-Content -Raw 读中文文件后再传 --body
$body = Get-Content "comment.md" -Raw
gitcode issue comment <n> --body $body
# ❌ 用 Set-Content / Out-File 默认编码写文件（不是 UTF-8）
$bodyContent | Set-Content "$env:TEMP\comment.md"
gitcode pr create 的特殊处理
gitcode pr create 不支持 --labels 参数，标签需创建后通过 gitcode pr edit 补打。--body-file 已支持，含中文 PR 描述可直接一步到位：
# 1. 创建 PR（--body-file 直接传中文描述）
[System.IO.File]::WriteAllText("$env:TEMP\pr-body.md", $chineseContent, [System.Text.Encoding]::UTF8)
gitcode pr create -R <owner/repo> --title "feat: ..." --body-file "$env:TEMP\pr-body.md" --base main
# 2. 补打 ai-assisted 标签
gitcode pr edit <pr-number> -R <owner/repo> --labels ai-assisted
修复已发出的乱码评论
[System.IO.File]::WriteAllText("$env:TEMP\fix.md", $fixedContent, [System.Text.Encoding]::UTF8)
gitcode issue comment edit <comment-id> --body-file "$env:TEMP\fix.md"
双轨产出（Issue 评论 + Artifact 文件）
每个变更同时产生两类产物，互为备份：
| 轨道 | 形式 | 存储位置 | 用途 |
|---|---|---|---|
| Issue 评论 | GitCode Issue / PR 评论区 | 远端 | 团队协作、PR 关联、审计追踪 |
| Artifact 文件 | proposal.md / design.md / tasks.md / archive.md | specs/spec/<repo-name>/task_design/<change-name>/ |
历史追溯、新人 onboard、平台无关 |
两者内容应该一致——artifact 文件组装后可作为 Issue 评论内容发布。Issue 评论是审计入口，artifact 是版本化备份。
用户要求在 Issue 评论区同步进展时，把当前阶段的 artifact 内容用 gitcode issue comment --body-file 发布。
合规检查清单（每个 Phase 收尾输出）
Phase N 合规检查:
[ ] 步骤 1: <step> — <evidence>
[ ] 步骤 2: <step> — <evidence>
...
[ ] Artifact 已落盘（如模式要求）: <path>
[ ] Issue 评论已发布（如用户要求同步）: <comment_link>
缺失项: <list or "无">
是否允许进入下一阶段: [ ]
把这个清单作为 Phase 转换闸门的标准化输出格式。