opc/dev_harness

Fork 0

Table of Contents

开发工作流

事实来源边界
一次任务怎样完成

1. 讨论
2. 建单

依赖与并行

3. 实施
4. 待验收
5. 归档和关闭

文档同步规则
面向初级维护者的修改边界
每个任务的文档影响
需求记录与流转
稳定文档与任务归档
效率与范围控制

严格控制范围
渐进执行和修复
复用已验证事实
明确停止条件

自然语言快捷指令
什么时候重新确认方案
工单、Wiki 与 Git 分别写什么

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/ 仅供浏览和审查，不是长期文档编辑入口。

一次任务怎样完成

1. 讨论

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

2. 建单

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

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

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

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

依赖与并行

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

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

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

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

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

3. 实施

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

重要进度及时写回工单：

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

长期核心文档遵循唯一顺序：

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

任务归档默认只更新 Wiki，不自动导出到 docs/task/。不得先编辑本地镜像再反向覆盖 Wiki。

4. 待验收

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

5. 归档和关闭

使用以下命令只在 Wiki 创建任务归档页：

python dev_scripts/new_task_archive.py 123 "修复登录超时"

归档内容以 Wiki 页面为事实来源。默认不修改 wiki-docs.json，也不写入 docs/task/。把 Wiki 页面、revision 和实现提交哈希写回工单；用户明确验收通过后，关闭单元工单并勾选父工单中的任务。

只有用户明确提出时才导出任务归档：

python dev_scripts/export_task_archives.py        # 增量：新增或 revision 变化
python dev_scripts/export_task_archives.py --all  # 全量：读取全部线上任务归档

导出不得自动删除本地文件。docs/task/ 只是人工按需生成的只读快照，可能不是完整或最新的任务历史。

文档同步规则

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

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

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

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

每个任务的文档影响

单元任务必须明确选择：

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

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

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

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

需求记录与流转

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

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

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

需求按以下边界流转：

内容	事实来源	本地镜像
关键原始需求、确认后的单次任务需求	Gitea 单元任务工单	无
讨论、决定和需求变化	Gitea 工单正文或评论	无
长期有效的产品需求、业务规则和系统边界	对应 Gitea Wiki 主题页	`docs/`
完成后的实现、验证和遗留问题	Wiki 任务归档	人工按需导出的 `docs/task/` 快照（可能不完整）

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

稳定文档与任务归档

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

效率与范围控制

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

严格控制范围

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

渐进执行和修复

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

复用已验证事实

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

明确停止条件

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

自然语言快捷指令

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

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

补充边界：

方案未确认时，建工单、建工单并做 和 执行工单 #N 不得绕过确认；Agent 应停在方案确认。
前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
#N 验收通过 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
同步文档 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
导出任务归档 和 导出全部任务归档 必须由用户明确提出，其他快捷指令不隐式执行。
Gitea 工单保留讨论和过程，不把工单全文导出到本地；docs/task/ 只保存人工按需导出的 Wiki 最终任务归档快照。

什么时候重新确认方案

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

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

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

工单、Wiki 与 Git 分别写什么

信息	Gitea 工单	Gitea Wiki	Git / `docs` 镜像
讨论过程和临时方案	是	否	否
实施进度和阻塞	是	否	否
长期有效的最终方案	链接	是	镜像
测试结果与未验证内容	是	任务归档	按需镜像
提交哈希	是	任务归档	按需镜像
与具体代码版本绑定的说明	可链接	提供入口	是