4

Development-Workflow

ila edited this page 2026-08-26 20:39:32 +08:00

Table of Contents

• 开发工作流
• 事实来源边界
• Gitea 交互与工单最小读取
• 新项目 Wiki 初始化门禁
• 工单与设计证据双门禁
• 先判断是否需要工单
• 再判断设计证据
• 线上原型审核与按需导出
• 记录和重新确认
• 一次任务怎样完成
• 1. 讨论
• 2. 建单
• 依赖与并行
• 3. 实施
• 4. 待验收
• 5. 待验收和关闭
• 文档同步规则
• 面向初级维护者的修改边界
• 每个任务的文档影响
• 需求记录与流转
• 稳定文档与可选历史快照
• 效率与范围控制
• 严格控制范围
• 渐进执行和修复
• 复用已验证事实
• 明确停止条件
• 自然语言快捷指令
• 什么时候重新确认方案
• 工单、Wiki 与 Git 分别写什么

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

开发工作流

事实来源边界

• Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
• Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。
• Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
• 本地 docs/ 仅供浏览和审查，不是长期文档编辑入口。

Gitea 交互与工单最小读取

• 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
• MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
• 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
• 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
• 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
• 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
• 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。

新项目 Wiki 初始化门禁

从 DevHarness 创建新项目时，本地 docs/ 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环：

1. 先创建 Gitea 远端仓库并启用 Wiki，再把 wiki-docs.json 指向该仓库。
2. 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
3. 查询线上页面列表；没有 Home 时先创建 Home，回读正文并记录 revision，然后再创建或更新其他核心映射页面。
4. 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地 docs/ 文件替代这项证据。
5. 运行 python dev_scripts/harness.py sync --verify。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。

Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。

工单与设计证据双门禁

开始正式实现前依次判断“是否需要工单”和“需要什么设计证据”。原型确认不能代替方案、工单、安全检查或技术验证；工单存在也不能绕过原型确认。

先判断是否需要工单

以下改动必须建立单元任务工单：

• 新功能、数据库迁移、API 或运行时配置契约变化；
• 权限、安全、凭据、并发、数据删除、发布或其他高风险操作；
• 跨模块行为变化、重构、重大 UI、交互或导航变化；
• 无法确定影响范围、风险或是否改变既有行为的修改。

以下修改同时满足“范围明确、容易回退、不涉及上述必须建单项”时可以直接提交：

• 错别字、注释、文档措辞、格式化、导入排序、单文件内部变量改名；
• 不改变产品行为的类型标注、文档字符串、测试或已确认死代码清理；
• 单文件低风险缺陷，且只是恢复已有明确行为，不改变接口、数据库、状态、权限、安全、并发、流程、布局或可访问性；
• 纯界面显示文案，并满足本页的全部文案豁免条件。

直接提交仍要保留无关工作区改动、执行受影响的最小验证并写清提交说明。有任何不确定就建单。

纯界面显示文案豁免还必须同时满足：

• 只修改用户看到的组件显示名称、按钮文字、标题、提示语或其他文案；
• 不改变业务含义、操作流程、权限、状态、接口、数据和验收结果；
• 不涉及法律条款、安全提示、支付、金额、单位或其他高风险含义；
• 不修改国际化键、代码组件名、类名、变量、API 字段、数据库字段或其他程序标识符；
• 不造成明显布局、截断、换行、可访问性或支持平台问题。

再判断设计证据

修改类型	最低设计证据	正式编码门禁
纯显示文案且满足全部豁免条件	无原型	完成最小界面检查即可
现有界面的小范围样式或布局调整	标注截图或低保真线框图；没有设计不确定性时说明复用的现有规范	工单确认设计证据后编码
新组件但复用现有设计体系	组件状态、错误和边界说明；按需提供低保真图	工单确认状态和复用边界后编码
新页面、独立用户功能、重大交互或导航变化	Quant-UX 或其他合适工具制作的可审阅原型	用户确认原型和文字需求后才能编写生产代码
后端、接口、数据处理或定时任务	架构、API、数据、状态或流程设计	用户确认技术方案后编码，不制作无意义的 UI 原型
恢复既有确认行为的 Bug	原设计、已确认截图、复现步骤或现有验收证据	确认是恢复而不是改变行为后修复

采用最低成本、足以让用户确认的证据，不为了形式制作高保真原型。草稿原型可以用于需求讨论；草稿需要写入 Git/Wiki、多人协作或单独实施时，应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。

线上原型审核与按需导出

新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后，默认直接通过线上原型审核，不要求每次导出本地 HTML：

• 可编辑设计源保存在 Quant-UX 或原设计工具；工单和 Wiki 只保存链接、版本与确认记录，不复制为第二份可编辑事实来源。
• 线上链接必须能被确认人访问，并能通过版本、revision、复制版本或确认日期识别本次审核对象；无法访问或无法区分版本时停止审核，等待用户确认等效方案。
• 提交审核前检查主要页面、流程、状态和交互可访问，并删除令牌、真实账号、个人信息和生产数据。
• 页面结构、主要流程、状态、权限、异常处理或验收结果变化时，更新线上原型并重新确认；不得用旧确认覆盖新版本。
• 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 仍只使用双门禁表规定的最低证据，不强制建立完整线上原型。

只有用户明确发出 导出原型 #N、导出全部原型，或项目专用规则明确要求离线交付时，才导出本地 HTML：

• 指定工单的快照放入 prototypes/<工单号>/<版本>/index.html；全部导出时也按工单和版本分目录，先在工单明确导出范围。
• 图片、样式、脚本和字体使用版本目录内的相对路径；需要网络资源才能显示时不得标记为可离线浏览。
• 已确认的本地快照不得原位覆盖；新版本使用新目录，已有快照继续作为历史审核证据。
• 导出后检查入口、主要交互和资源完整性；浏览器限制直接打开时，在工单记录最小本地静态服务命令和访问地址，不新增项目专用服务脚本。
• 导出指令只生成或更新请求范围内的快照并报告结果，不自动提交；用户未明确要求时不得顺带导出其他原型。
• 设计工具无法生成用户要求的可用 HTML 时，在工单记录限制并停止该导出或离线交付，等待用户确认等效方案；线上原型仍可访问且版本明确时，不因此阻塞线上审核。

记录和重新确认

需要设计证据的工单必须记录：

• 原型或设计的线上链接、对应事实来源，以及链接可访问性；
• 版本、revision、复制版本或确认日期，以及审核版本的识别方式；
• 状态：无、草稿、已确认或已废弃；
• 只有显式导出时才记录本地 HTML 路径、版本和资源检查结果；
• 确认人和确认时间；
• 本次确认覆盖的页面、组件、流程和边界；
• 不需要 UI 原型时采用的技术设计，或无需任何原型的原因。

页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新原型或文字需求并重新确认，再继续正式编码。只读技术检查可以在确认前进行；确需可行性代码验证时，必须由用户明确同意，隔离为不可进入生产的技术验证，不得悄悄扩展成正式实现。

一次任务怎样完成

1. 讨论

用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。

2. 建单

方案确认后，使用 .gitea/issue_template/task.md 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。

新产品或较大版本先建立 Epic，再建立 MVP：

[Epic] 产品或长期目标
└── [MVP] 第一个可交付版本
    ├── #101 单元任务
    ├── #102 单元任务
    └── #103 单元任务

每个单元任务都应目标单一，能够独立测试、提交和回退。

依赖与并行

建立新工单不要求其他工单已经完成，也不按工单编号限制实施顺序。每个单元任务必须声明：

• 前置工单，没有时填写“无”；
• 是否允许与未完成的前置工单并行；
• 判断可以或不可以并行的原因。

开始修改前，Agent 检查工单声明的前置工单：

• 没有前置工单，或前置工单已经完成，可以进入“进行中”；
• 前置工单未完成且存在实际依赖时，不得开始实施，工单保持“待实施”；
• 与前置工单没有实施冲突、允许并行时，可以进入“进行中”，但必须在工单写明原因；
• 已经进入实施后出现计划外、当前无法解除的问题，才使用“阻塞”。

依赖不改变单元任务边界。依赖满足后，该任务仍须拥有独立的范围、提交、测试和回退方式。

3. 实施

Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。

重要进度及时写回工单：

• 已确认的根因；
• 方案或范围变化；
• 测试结果；
• 阻塞和未验证内容；
• Git 提交哈希；
• 相关 Wiki 页面及 revision。

工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和长期文档影响，保留可追溯时间线，不在 Wiki 重抄同一份任务结果。

只有长期事实发生变化时才执行核心文档闭环：

修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像

没有长期文档影响时，在工单写明原因并跳过 Wiki 更新和核心镜像同步；默认任务流程不创建任务归档。长期文档仍不得先编辑本地镜像再反向覆盖 Wiki。

4. 待验收

实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。

5. 待验收和关闭

实现、必要测试和提交完成后，在工单追加一条最终证据评论并保持“待验收”。评论至少记录最终差异、测试结果、未验证内容、提交哈希，以及长期 Wiki 页面和 revision，或“无长期文档影响”及原因。

用户明确验收通过后：

1. 在工单追加验收时间和结论，不重复抄写已有测试与提交证据；
2. 关闭单元工单并勾选所属 MVP/Epic 子任务；
3. 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki；
4. 默认不创建或导出任务归档。

任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行：

python dev_scripts/harness.py archive 123 "修复登录超时"
python dev_scripts/harness.py export        # 增量导出已有归档
python dev_scripts/harness.py export --all  # 全量导出已有归档

可选归档不得成为第二个日常维护入口；创建时以工单中的最终证据为来源，并记录工单链接。既有 Wiki 归档和 docs/task/ 快照不自动删除、重命名或补齐。

文档同步规则

• 核心页面映射保存在 wiki-docs.json；普通同步只处理这些核心长期文档。
• 可选任务归档不逐页登记映射；显式执行归档导出时，工具根据 Task-<编号>-<标题> 动态发现，已有镜像优先按镜像头匹配原页面。
• 所有同步和导出只实现 Wiki → docs/，不提供反向同步。
• 镜像头必须记录页面名、页面地址、revision 和同步时间。
• 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
• 核心同步的 --check 只检查核心镜像，不要求线上任务归档全部存在于本地。
• 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。
• 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
• Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
• 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。

面向初级维护者的修改边界

风险	示例	处理方式
低	文案、简单校验、查询条件、独立 UI、小范围回归 Bug	初级程序员可在 Agent 协助下理解、修改和验证
中	API、配置、依赖、跨模块逻辑、数据结构	由 Agent 实现，程序员检查差异并执行验证
高	权限、安全、并发、迁移、支付、删除数据、不可逆操作	停止修改，由 Agent 分析并等待人工确认

风险由影响范围决定，不按代码行数判断。

每个任务的文档影响

单元任务必须明确选择：

• 不影响长期文档，并说明原因；
• 更新项目档案或运行验证；
• 更新架构与代码地图；
• 更新业务规则与术语；
• 更新常见修改或故障排查；
• 新增或调整其他 Wiki 页面。

以下变化必须更新相关 Wiki：

• 启动、测试、部署或排错命令变化；
• 模块入口、目录职责或主要调用路径变化；
• 配置项、API、数据结构或状态变化；
• 业务规则、安全边界或权限变化；
• 日志位置、错误定位或常见处理方式变化。

部署命令的落点：有常驻服务的项目更新自己的 Deployment-and-Operations 页面（由部署文档模板复制建立）；没有常驻服务的项目在工单记录“无部署文档影响”及原因，不要创建空的部署页。

普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。

需求记录与流转

聊天用于分析和确认，不是正式需求的长期事实来源。创建单元任务工单时，Agent 应记录：

• 原始需求的来源和提出时间；
• 能表达用户目的、使用场景和限制的少量关键原话；
• 整理后的目标、非目标、确认方案、验收标准和文档影响；
• 实施期间影响范围、接口、数据、风险或验收的需求变化，以及变化原因和用户确认。

只摘录完成追踪所需的内容，不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据。包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。

需求按以下边界流转：

内容	事实来源	本地镜像
关键原始需求、确认后的单次任务需求	Gitea 单元任务工单	无
讨论、决定和需求变化	Gitea 工单正文或评论	无
长期有效的产品需求、业务规则和系统边界	对应 Gitea Wiki 主题页	docs/
完成后的实现、验证、遗留问题和验收	Gitea 单元任务工单正文与评论	无；用户明确要求时可创建专项 Wiki 快照

任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。

稳定文档与可选历史快照

• Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
• 工单正文和评论解释某次为什么修改、实际改了什么、如何验证以及怎样验收。
• 新人先读稳定主题页，只有追查历史原因时才读工单；可选 Wiki 快照和本地任务快照只是专项或历史兼容资料，不是默认事实来源。
• 任务产生的长期结论必须合并到对应主题页，不能只留在工单或可选快照。

效率与范围控制

本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。

严格控制范围

• 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
• 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
• 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
• 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。

渐进执行和修复

• 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
• 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
• 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
• 不在真实证据出现前堆叠与已知风险无关的预防性检查。
• 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。

复用已验证事实

• 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
• 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
• 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
• Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。

明确停止条件

• 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
• “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
• 未影响当前验收的相邻问题只提示或建单，不顺手处理。

自然语言快捷指令

快捷指令是对本工作流的自然语言别名，供 Claude Code、Codex 和维护者使用。它们只减少重复描述，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收。

指令	执行动作	停止位置
只分析	只读检查需求、代码、日志和文档，区分事实与假设并给出方案	输出方案并等待确认；不建单、不修改
建工单	根据已经确认的方案创建单元任务工单	工单创建并记录完成；不修改代码
执行工单 #N	读取工单和前置依赖，实施、测试、提交并回写证据；仅有长期文档影响时更新 Wiki 和镜像	工单保持“待验收”
建工单并做	依次执行“建工单”和“执行工单”；建工单，做、建工单,做 含义相同	工单保持“待验收”
继续工单 #N	核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查	到达该工单当前流程的停止条件
检查工单 #N	只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分	输出检查报告；不自动修复
同步文档	读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档	显示结果和差异；不修改 Wiki、不自动提交
导出原型 #N	人工触发导出指定工单已确认的原型版本；按工单和版本写入 prototypes/	显示路径和检查结果；不扩展范围、不自动提交
导出全部原型	人工触发导出当前项目明确范围内的全部已确认原型	显示导出范围和结果；不自动提交
导出任务归档	人工触发增量导出，只写入新增或 revision 已变化的任务归档	显示导出或跳过结果；不删除本地文件、不自动提交
导出全部任务归档	人工触发全量读取并导出线上全部任务归档	显示导出结果；不删除本地文件、不自动提交
#N 验收通过	在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档	工单“已完成”并关闭

补充边界：

• 方案未确认时，建工单、建工单并做 和 执行工单 #N 不得绕过确认；Agent 应停在方案确认。
• 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
• #N 验收通过 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
• 同步文档 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
• 导出原型 #N 和 导出全部原型 必须由用户明确提出或项目专用规则明确要求；其他指令不隐式导出原型。
• 导出任务归档 和 导出全部任务归档 必须由用户明确提出，其他快捷指令不隐式执行。
• Gitea 工单是单次任务唯一事实来源，不导出全文；docs/task/ 只保存人工明确要求的专项或历史兼容快照。

什么时候重新确认方案

以下变化必须先更新工单，再由用户确认：

• 交付结果或用户操作发生变化；
• 增加或删除接口、数据库字段或迁移；
• 安全边界、权限或不可逆操作发生变化；
• 原方案不可行，需要更换主要技术路线；
• 任务范围明显扩大；
• Wiki 页面删除、重命名或事实源边界改变。

普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。

工单、Wiki 与 Git 分别写什么

信息	Gitea 工单	Gitea Wiki	Git / docs 镜像
讨论过程和临时方案	是	否	否
实施进度和阻塞	是	否	否
长期有效的最终方案	链接	是	镜像
测试结果与未验证内容	是	否	否
提交哈希和验收结论	是	否	否
用户明确要求的任务专项快照	提供来源	可选	可选导出
与具体代码版本绑定的说明	可链接	提供入口	是