chore: initialize DevHarness template

2026-08-07 23:11:53 +08:00
commit d6706f7c69
13 changed files with 588 additions and 0 deletions
@@ -0,0 +1,50 @@
+# 项目档案
+
+复制模板后先填写本页。这里保存不经常变化、所有维护者都需要知道的信息。
+
+## 基本信息
+
+| 项目 | 内容 |
+|---|---|
+| 项目名称 | `<填写>` |
+| 一句话目标 | `<填写>` |
+| Gitea 地址 | `<例如 https://gitea.example.com>` |
+| 仓库 | `<owner/repository>` |
+| 默认分支 | `main` |
+| 主要维护者 | `<填写>` |
+
+## 技术栈
+
+| 部分 | 技术 | 规则文件 |
+|---|---|---|
+| `<子项目或服务>` | `<语言、框架、版本>` | `<路径/AGENTS.md>` |
+
+## 常用命令
+
+所有命令默认从仓库根目录执行。
+
+| 用途 | 命令 | 预期结果 |
+|---|---|---|
+| 安装依赖 | `<填写>` | `<填写>` |
+| 启动开发环境 | `<填写>` | `<填写>` |
+| 格式检查 | `<填写>` | `<填写>` |
+| 静态检查 | `<填写>` | `<填写>` |
+| 单元测试 | `<填写>` | `<填写>` |
+| 集成测试 | `<填写或写“不适用”>` | `<填写>` |
+
+## 目录边界
+
+| 目录 | 职责 | 不应放入 |
+|---|---|---|
+| `<路径>` | `<填写>` | `<填写>` |
+
+## 环境与凭据
+
+- 本地配置文件：`<填写>`
+- 配置示例文件：`<填写>`
+- 凭据保存位置：`<只写保存方式，不填写真实凭据>`
+- 日志和构建产物位置：`<填写>`
+
+## 项目专用验收要求
+
+- `<填写>`
@@ -0,0 +1,72 @@
+# 开发工作流
+
+## 一次任务怎样完成
+
+### 1. 讨论
+
+用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍，让用户确认。
+
+### 2. 建单
+
+方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码。
+
+新产品或较大版本先建立 Epic，再建立 MVP：
+
+```text
+[Epic] 产品或长期目标
+└── [MVP] 第一个可交付版本
+    ├── #101 单元任务
+    ├── #102 单元任务
+    └── #103 单元任务
+```
+
+每个单元任务都应目标单一，能够独立测试、提交和回退。
+
+### 3. 实施
+
+Agent 检查工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果它不影响当前验收，另建工单，不扩大当前任务。
+
+重要进度应及时写回工单：
+
+- 已确认的根因；
+- 方案或范围变化；
+- 测试结果；
+- 阻塞和未验证内容；
+- Git 提交哈希。
+
+### 4. 待验收
+
+实现和测试完成后，Agent 提交代码并将工单更新为待验收。用户验收前工单保持开启。
+
+### 5. 归档和关闭
+
+使用以下命令创建归档草稿：
+
+```powershell
+python scripts/new_task_archive.py 123 "修复登录超时"
+```
+
+填写实际结果后单独提交归档，再把路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
+
+## 什么时候重新确认方案
+
+以下变化必须先更新工单，再由用户确认：
+
+- 交付结果或用户操作发生变化；
+- 增加或删除接口、数据库字段或迁移；
+- 安全边界、权限或不可逆操作发生变化；
+- 原方案不可行，需要更换主要技术路线；
+- 任务范围明显扩大。
+
+普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。
+
+## 工单与文档分别写什么
+
+| 信息 | Gitea 工单 | `docs/task` |
+|---|---:|---:|
+| 讨论过程和临时方案 | 是 | 否 |
+| 实施进度和阻塞 | 是 | 否 |
+| 最终实现方案 | 是 | 是 |
+| 测试结果与未验证内容 | 是 | 是 |
+| 提交哈希 | 是 | 是 |
+| 长期有效的最终结论 | 可链接 | 是 |
@@ -0,0 +1,8 @@
+# 文档索引
+
+- [项目档案](00-project-profile.md)：仓库、技术栈、命令和负责人等稳定信息。
+- [开发工作流](01-workflow.md)：从需求讨论到工单关闭的完整顺序。
+- [任务归档模板](templates/task-archive.md)：任务完成后的固定格式。
+- `task/`：已经完成并与代码版本对应的任务记录。
+
+临时进度、方案讨论和待办事项写入 Gitea 工单，不写进长期文档。
@@ -0,0 +1 @@
+
@@ -0,0 +1,40 @@
+# <工单号> <标题>
+
+- 类型：需求 / 缺陷 / 重构
+- 所属 Epic：#
+- 所属 MVP / 版本：#
+- 状态：待验收 / 已完成
+- 日期：YYYY-MM-DD
+- Gitea 工单：<链接>
+
+## 背景与目标
+
+<!-- 原来有什么问题，这次达到什么结果。 -->
+
+## 最终方案
+
+<!-- 说明实际实现。与建单方案不同之处必须写清原因。 -->
+
+## 修改文件
+
+- `<文件>`：<改动说明>
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+|  | 通过 / 未通过 |
+
+## 测试
+
+- 执行命令：`<命令>`
+- 结果：
+- **未验证部分**：<!-- 必填；没有就写“无”。 -->
+
+## 遗留问题
+
+<!-- 没有就删除本节。 -->
+
+## 相关提交
+
+- `<提交哈希>` <提交说明>