本地开发全链路工作流

这是一个"总调度"技能，定义 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。

步骤速查表

异常处理

• •质量门禁失败：回到 Step 3 修复代码，再从 Step 5 重新验证
• •用户中途改需求：回到 Step 2 重新对齐方案
• •需要删除文件：先创建备份，再执行删除（AGENTS.md 硬性要求）