Table of Contents
开发工作流
事实来源边界
- Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
- Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。
- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
- 本地
docs/仅供浏览和审查，不是长期文档编辑入口。
语言与术语
- 用户可以使用中文、英文或合理的中英混合语言提出需求和补充信息；Agent 不要求用户先翻译。
- Agent 默认使用中文进行分析、回复、工单记录和内部项目文档维护。
- 代码标识符、命令、参数、路径、文件名、API 名称、协议名、日志和错误原文保持原样，不做会影响搜索、复制、执行或排错的翻译。
- commit、revision、middleware 等通用英文术语可以保留；可能影响初级维护者理解时，在首次出现处补充简短中文解释，不反复注释。
- 用户明确要求某次回复、交付物或对外文档使用其他语言时，按该次明确要求执行；默认中文不是禁止其他交付语言的门禁。
- 引用外部材料时保留必要原文并用中文说明结论；不得为了语言统一改写事实、错误信息或接口契约。
Gitea 交互与工单最小读取
- 所有 Gitea 工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭操作，优先使用项目已配置的 Gitea MCP。
- MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录回退原因；初始化阶段尚无工单时记录到初始化工单草稿，建单后补回。凭据只从环境或 MCP 安全配置读取。
- 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省 Token 跳过范围、依赖、安全、验收或重要变更。
- 同一任务、同一会话且关键前提未变化时，复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤，不重复分析已经确认且仍有效的内容。
- 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，任务基线不清楚，或最新评论声明历史需求、方案、范围、风险或验收发生变化时，重新读取必要历史；无法判断影响范围时读取完整工单。
- 连接器不支持评论分页或增量读取时允许读取完整工单，但不得把“已读取全文”误当成需要重新分析全部历史，也不得为规避完整读取而新增本地工单、缓存或第二事实来源。
- 正确性、安全规则和已确认范围优先于 Token 优化；读取边界存在不确定时补读必要证据。
新项目 Wiki 初始化门禁
从 DevHarness 创建新项目时，本地 docs/ 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环：
- 先创建 Gitea 远端仓库并启用 Wiki，再把
wiki-docs.json指向该仓库。 - 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
- 查询线上页面列表；没有
Home时先创建Home，回读正文并记录 revision，然后再创建或更新其他核心映射页面。 - 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地
docs/文件替代这项证据。 - 运行
python dev_scripts/harness.py sync --verify。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。
Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。
按治理模式选择最小门禁
使用 DevHarness 创建新项目时默认采用轻量模式。只有项目负责人明确选择标准或高风险模式，并在 Project-Profile 记录理由时，才改变项目默认模式；未明确填写时按轻量模式执行并提示补写，不因此阻塞产品开发。DevHarness 上游模板自身继续采用标准模式。单个任务风险高于项目默认模式时，只升级该任务，不抬高全部日常工作。不得为了流程完整而增加没有实际作用的工单、原型、文档或测试。
不可裁剪底线
任何治理模式都必须遵守：
- 密码、令牌、Cookie 和私钥只从环境或安全配置读取，不得写入代码、Git、日志、工单、Wiki 和文档；人工授权不改变此边界；
- 任务确有需要且得到人工明确授权时，可以在授权范围内处理真实个人数据或生产数据；只使用完成任务所需的最少数据，不把无关副本扩散到代码、Git、Wiki、工单、测试数据和日志，证据优先使用脱敏摘要；
- 手机号等明确为虚构的测试数据无需形式化脱敏，但必须能与真实用户数据区分；来源不明时按真实个人数据处理；
- 未经人工明确授权，不执行发布、付款、删除数据、破坏性迁移或其他不可逆操作；授权有效时按下一节执行；
- 测试结果必须真实，未执行或无法覆盖的验证必须说明；
- 任务涉及权限、安全、支付、真实个人/生产数据、迁移、并发、删除或不可逆操作时按高风险处理；尚未获得有效授权时等待人工确认，已经获得时不重复确认。
明确授权后的执行
- 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据；不要求把聊天授权重复复制到工单后再确认。
- 授权必须能识别操作、对象和范围。Agent 自动生成的工单、草稿、摘要或对用户意图的转述，不能单独构成人工授权。
- 获得有效授权后，Agent 只核对准确目标、授权范围和当前状态等最小必要前提，然后执行；不得仅因操作不可逆而重复询问或拒绝。
- 授权只适用于明确范围，不自动覆盖相邻对象或后续任务。环境、对象、范围或影响发生实质变化时，原授权不再覆盖变化部分，应重新确认。
- 平台自身强制的审批、安全策略或权限限制继续有效；不能把项目内授权解释为绕过平台限制。
- 执行完成后报告实际结果、影响范围以及是否可以恢复；失败时报告已完成部分和当前状态。
先判断是否需要工单
| 治理模式 | 可直接实施 | 必须建单 |
|---|---|---|
| 轻量 | 文案、注释、格式、局部样式或布局；预期行为明确的小 Bug；不改变接口、数据结构、权限和安全边界的单模块低风险调整 | 完整独立需求、新页面或跨模块功能；API、数据结构、权限、安全、迁移；范围或预期不明确的变化 |
| 标准 | 纯文档措辞、格式化、内部标识符改名和确定不改变行为的小整理 | 新功能、缺陷修复、重构及用户可感知的行为变化 |
| 高风险 | 只读诊断和不会改变行为的文档整理 | 任何正式行为变化；按风险补充人工确认和验证 |
直接实施项无需为了留痕补建工单，也无需填写工单模板；开始前只做必要的工作区和安全检查，完成最小测试后报告结果。无法确定是否符合直接实施条件时，先澄清或建单，不用代码行数代替风险判断。
再判断设计证据
- 轻量模式的小 Bug、局部样式或布局、复用现有规范的组件调整无需完整原型；能用一句话、现有界面或标注截图确认时即停止增加设计材料。
- 完整独立需求、新页面、重大交互或导航变化需要工单；只有存在明显交互不确定性、用户明确要求，或返工成本显著时，才制作 Quant-UX 或其他可审阅原型。
- 标准模式对新页面、独立用户功能和重大交互使用可审阅原型；小范围 UI 使用最低成本的文字、截图或低保真证据。
- 高风险任务按影响补充技术设计、数据和权限边界、回退方案及人工确认；非 UI 任务不制作无意义的 UI 原型。
- 恢复既有确认行为的 Bug 可以复用原设计、截图、复现步骤或已有验收证据。
线上原型审核与按需导出
需要完整原型时，默认通过 Quant-UX 或等效工具的可访问线上链接审核，记录可识别的版本和确认范围。只有用户明确发出 导出原型 #N、导出全部原型，或项目专用规则要求离线交付时，才导出到 prototypes/<工单号>/<版本>/index.html；不得把本地快照变成第二份可编辑事实来源。
页面结构、主要流程、权限、状态或异常处理发生影响验收的变化时，才更新设计证据并重新确认。设计工具无法生成用户明确要求的离线 HTML 时，记录限制并等待等效方案；线上版本可访问且可识别时不阻塞线上审核。
一次任务怎样完成
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，或“无长期文档影响”及原因。
用户明确验收通过后：
- 在工单追加验收时间和结论，不重复抄写已有测试与提交证据；
- 关闭单元工单并勾选所属 MVP/Epic 子任务；
- 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki；
- 默认不创建或导出任务归档。
任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行：
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 和同步时间。
- 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
sync和sync --check先读取一次页面列表，并用远端 revision 与本地镜像头比较；revision 未变化时不下载正文，只有页面新增、变化、元数据缺失或本地镜像元数据无效时才读取正文。sync --check是核心镜像的日常快速检查，不要求线上任务归档全部存在于本地；它验证 revision 和镜像元数据，不替代正文审计。sync --deep-check显式下载全部映射页面正文并逐页比较，用于疑似镜像损坏、同步算法审计或人工要求的完整核对。sync --verify用于新项目 Wiki 初始化门禁，完整读取并写入核心镜像后执行严格结构检查；同一次运行复用读取结果，不重复下载正文。- 已经导出的任务镜像仍必须具有来源页面、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 工单为单次任务事实来源，不导出全文；符合轻量模式直接实施条件的任务以用户确认范围、Git 提交和结果报告留痕，不补建工单。
docs/task/只保存人工明确要求的专项或历史兼容快照。
什么时候重新确认方案
以下变化必须重新确认；已有工单时先更新工单，直接实施项遇到这些变化时不再符合豁免，先建单再继续：
- 交付结果或用户操作发生变化；
- 增加或删除接口、数据库字段或迁移；
- 安全边界、权限或不可逆操作发生变化；
- 原方案不可行，需要更换主要技术路线；
- 任务范围明显扩大；
- Wiki 页面删除、重命名或事实源边界改变。
普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。
工单、Wiki 与 Git 分别写什么
| 信息 | Gitea 工单 | Gitea Wiki | Git / docs 镜像 |
|---|---|---|---|
| 讨论过程和临时方案 | 是 | 否 | 否 |
| 实施进度和阻塞 | 是 | 否 | 否 |
| 长期有效的最终方案 | 链接 | 是 | 镜像 |
| 测试结果与未验证内容 | 是 | 否 | 否 |
| 提交哈希和验收结论 | 是 | 否 | 否 |
| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 |
| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |