# Local Dev Workflow > 本地开发全链路 SOP。接到任何开发任务时，按此流程从需求理解到 Git 管理完整执行，串联所有子 Skills 形成闭环。 Use when this capability is needed. - Skill: `tomevault-io/local-dev-workflow` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/local-dev-workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/local-dev-workflow/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/local-dev-workflow --- # 本地开发全链路工作流 这是一个"总调度"技能，定义 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：本地预览 **做什么**：启动开发服务器，确认页面效果正常。 ```bash cd web && npm run dev ``` 检查要点： - 页面能正常加载，无白屏 - 新功能按预期展示 - 已有功能未被破坏 **完成标志**：页面视觉和交互符合预期。 > 💡 对于纯数据/配置变更或非前端代码，此步骤可跳过。 --- ### Step 5：质量门禁 **做什么**：运行全链路构建检查。 → **调用 `build-check` skill** ```bash bash scripts/check_errors.sh ``` 如有测试文件变更，额外运行： ```bash 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](https://tomevault.io/claim/shouxinzhang) — claim your Tome and manage your conversions.