local-dev-workflow

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 硬性要求）