| name | local-dev-workflow |
| description | 本地开发全链路 SOP。接到任何开发任务时,按此流程从需求理解到 Git 管理完整执行,串联所有子 Skills 形成闭环。 |
本地开发全链路工作流
这是一个"总调度"技能,定义 Agent 从接到开发任务到代码进入版本库的完整流程。每个步骤明确做什么、怎么验证、何时进入下一步。
完整流程
接收需求 → 理解现有代码 → 方案对齐 → 编码实现 → 本地预览 → 质量门禁 → 架构文档同步 → 开发日志 → Git 管理
Step 1:需求理解
做什么:读取项目规范和现有架构,理解上下文。
必读:
AGENTS.md — 行为规范、正负面 Prompt
- 与任务相关模块说明(优先通过 MCP 按目标模块/叶子节点读取)
兜底读取(仅在下列场景触发):
docs/architecture/repository-structure.md — 当变更范围不清晰、MCP 不可用、或涉及跨模块影响评估时
可选读取(按需):
- 相关功能的现有源代码
docs/dev_logs/ 近期开发日志,了解最近改了什么
完成标志:清楚知道项目当前的技术栈、目录结构、编码规范。
Step 2:方案对齐
做什么:先向用户描述实现方案,等用户确认后再动手。
必须包含:
- 要修改/新增哪些文件
- 大致的实现思路
- 对现有功能的影响
完成标志:用户明确表示 OK / 可以 / 开始。
⚠️ 绝不跳过此步骤直接写代码。这是 AGENTS.md 的硬性要求。
Step 3:编码实现
做什么:按确认的方案编写代码。
编码规范(摘自 AGENTS.md):
- 模块化设计,不同模块不互相干扰
- 新代码放在叶子目录,禁止放高层模块
- 先审查现有代码减少冗余
- 保持变更尽可能简单,不加额外分支
- 业务结果优先
如涉及知识图谱数据:
- → 调用
knowledge-tree-update skill 的规范
完成标志:代码编写完成,准备验证。
Step 4:本地预览
做什么:启动开发服务器,确认页面效果正常。
cd web && npm run dev
检查要点:
- 页面能正常加载,无白屏
- 新功能按预期展示
- 已有功能未被破坏
完成标志:页面视觉和交互符合预期。
💡 对于纯数据/配置变更或非前端代码,此步骤可跳过。
Step 5:质量门禁
做什么:运行全链路构建检查。
→ 调用 build-check skill
bash scripts/check_errors.sh
如有测试文件变更,额外运行:
cd web && npm run test
完成标志:所有检查项均为 ✔ 通过。如有失败,修复后重新运行直到全部通过。
⚠️ 质量门禁不通过,禁止进入后续步骤。
Step 6:架构文档同步
做什么:如果本次开发涉及文件结构变化(新增/删除/移动文件或目录),更新架构文档。
→ 调用 repo-structure-sync skill
触发条件:
- 新增了文件或目录
- 删除了文件或目录
- 新增了 npm 依赖或 scripts
完成标志:docs/architecture/repository-structure.md 与实际文件结构一致。
💡 如果本次只修改了现有文件内容(未新增/删除),此步骤可跳过。
Step 7:开发日志
做什么:记录本次开发的完整日志。
→ 调用 dev-logs skill
日志文件路径:docs/dev_logs/{YYYY-MM-DD}/{序号}-{简短描述}.md
必须包含:
- 对话记录(按轮次包含:背景、用户原文、用户意图解析、LLM思考摘要)
- 修改时间(精确到秒)
- 修改文件清单(表格)
- 具体变更描述
- 构建验证结果
完成标志:日志文件已创建,内容完整。
Step 8:Git 管理
做什么:根据任务风险使用 git-management skill 管理提交节奏和保护点。
→ 调用 git-management skill
最小要求:
- 有阶段性成果或准备大改动时,必须执行 Git 保护点/提交动作
- 若产生 commit,必须把分支名与 commit hash 回写到本轮开发日志
完成标志:
- 完成了符合风险级别的 Git 保护(提交/备份分支/检查点标签)
- 开发日志已记录 Git 锚点(branch / commit / tag)
💡 只做 commit,是否 push 由用户决定。如用户要求了 push,执行 git push。
步骤速查表
| # | 步骤 | 可跳过? | 关联 Skill |
|---|
| 1 | 需求理解 | ❌ | — |
| 2 | 方案对齐 | ❌ | — |
| 3 | 编码实现 | ❌ | knowledge-tree-update(按需) |
| 4 | 本地预览 | ✅ 非前端变更可跳 | — |
| 5 | 质量门禁 | ❌ | build-check |
| 6 | 架构文档同步 | ✅ 无文件结构变化可跳 | repo-structure-sync |
| 7 | 开发日志 | ❌ | dev-logs |
| 8 | Git 管理 | ❌ | git-management |
异常处理
- 质量门禁失败:回到 Step 3 修复代码,再从 Step 5 重新验证
- 用户中途改需求:回到 Step 2 重新对齐方案
- 需要删除文件:先创建备份,再执行删除(AGENTS.md 硬性要求)