tomevault-io 本地开发全链路工作流
这是一个"总调度"技能，定义 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-updateskill 的规范
完成标志：代码编写完成，准备验证。
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 硬性要求）
Converted and distributed by TomeVault — claim your Tome and manage your conversions.