OPC/dev_harness
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

项目档案改为按需读取并内联常用命令 #22

New Issue
Closed
opened 2026-08-18 21:21:47 +08:00 by ila · 2 comments
ila commented 2026-08-18 21:21:47 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：重构
  • 所属 Epic：无
  • 所属 MVP / 版本：无
  • 阶段：实施

依赖与并行

  • 前置工单：无
  • 是否允许与前置工单并行：是
  • 原因：无前置工单。与「合并 dev_scripts 入口脚本」工单同期进行，两者都会改 AGENTS.md 的命令表，实施时按先后顺序合并，不并发编辑同一段落。

子项目影响

  • 仅影响的子项目 / 交付单元：DevHarness 模板
  • 是否跨子项目：否
  • 是否修改共享接口或契约：否
  • 各子项目需要执行的验证：python dev_scripts/check_harness.py --strict、python -m unittest discover -s tests -v

原始需求

  • 来源：用户对话
  • 提出时间：2026-08-18
  • 关键原话或脱敏摘要：用户要求「为了更加节省开发时间和 token，分析项目文件给出最小化方案」，并在两轮追问中要求只保留能确认真实节省的部分，最终确认「先做 B + E」。

要解决什么

现状：AGENTS.md 开头写着「开始工作前先阅读项目档案」，这是一条无条件规则。docs/00-project-profile.md 约 2 100 tokens，且在每个新任务开始时都要重读一次，不命中 prompt cache。

实测该文件真正被高频使用的只有「常用命令」表（6 行）；其余章节（DevHarness 基线、子项目与交付单元、技术栈、目录边界、环境与凭据、项目专用验收要求）只在特定任务需要时才用得上。

目标：把高频的常用命令内联到 AGENTS.md，取消无条件读取，改为按需读取，减少每个任务的固定输入开销。

做什么 / 不做什么

  • 做：修改 AGENTS.md 的阅读入口规则；在 AGENTS.md 内联常用命令表；在 Wiki「开发工作流」中说明按需读取项目档案的触发条件。
  • 不做：不删减 docs/00-project-profile.md 的任何内容；不改变项目档案作为事实来源的地位；不动 CLAUDE.md 的模型路由；不合并脚本入口（属另一工单）。

已确认方案

  1. AGENTS.md 开头规则由「开始工作前先阅读项目档案和任务涉及目录中的 AGENTS.md」改为：无条件只要求阅读任务涉及目录的 AGENTS.md；项目档案改为按需读取，并列出触发条件（需要环境与凭据、目录边界、子项目与交付单元划分、DevHarness 基线、项目专用验收要求时）。
  2. 在 AGENTS.md 增加「常用命令」表，内联 check / test / sync / archive / export 命令，与项目档案保持一致。
  3. Wiki「Development-Workflow」页对应说明同步更新；随后导出核心镜像。

不影响接口、数据库和安全边界。原有安全红线、门禁和验收要求一字不改。

预计修改文件：

  • AGENTS.md
  • Wiki 页面 Development-Workflow → 镜像 docs/01-workflow.md

需求变化记录

日期 变化内容 原因 用户确认
2026-08-18 由最初的「AGENTS.md 整体瘦身 + 项目档案按需读」缩减为只做「项目档案按需读 + 命令内联」 经核算，AGENTS.md 瘦身的节省会被 prompt cache 吸收，且需同步改动 check_harness.py 的 34 条字面校验，回本周期长 是

设计与原型门禁

  • 修改类型：非 UI
  • 所需设计证据：架构、API、数据、状态或流程设计
  • 可编辑设计源链接、版本或事实来源：本工单「已确认方案」一节
  • 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，非 UI 改动
  • 本地浏览方式和资源完整性检查：不适用
  • 版本、revision 或确认日期：2026-08-18
  • 状态：已确认
  • 确认人、确认时间和覆盖范围：ila，2026-08-18，覆盖 AGENTS.md 阅读入口规则与常用命令表
  • 无需 UI 原型或无需任何原型的原因：只修改 Agent 规则文本与文档，无任何用户界面

文档影响

  • 更新项目档案或本地开发与验证
  • 更新其他 Wiki 页面：Development-Workflow

交付文档影响

  • 无交付文档影响，原因：本仓库为开发流程模板，无面向最终用户或其他岗位的交付文档受众变化

验收标准

  • AGENTS.md 不再包含「开始工作前先阅读项目档案」这类无条件要求，改为列出明确触发条件的按需读取
  • AGENTS.md 内含常用命令表，且命令与 docs/00-project-profile.md 完全一致
  • docs/00-project-profile.md 内容未被删改
  • Wiki Development-Workflow 已更新并回读取得 revision，核心镜像已导出
  • python dev_scripts/check_harness.py --strict 通过
  • python -m unittest discover -s tests -v 通过
  • python dev_scripts/sync_wiki_docs.py --check 通过

验证方式

python dev_scripts/check_harness.py --strict
python -m unittest discover -s tests -v
python dev_scripts/sync_wiki_docs.py --check

命令一致性由人工比对 AGENTS.md 与 docs/00-project-profile.md 的命令表确认。

风险和回退

低风险。规则文本改动，不涉及接口、迁移、安全或不可逆操作。回退方式：git revert 对应实现提交，并把 Wiki Development-Workflow 恢复到本工单记录的前一版 revision。

## 基本信息 - 类型：重构 - 所属 Epic：无 - 所属 MVP / 版本：无 - 阶段：实施 ## 依赖与并行 - 前置工单：无 - 是否允许与前置工单并行：是 - 原因：无前置工单。与「合并 dev_scripts 入口脚本」工单同期进行，两者都会改 AGENTS.md 的命令表，实施时按先后顺序合并，不并发编辑同一段落。 ## 子项目影响 - 仅影响的子项目 / 交付单元：DevHarness 模板 - 是否跨子项目：否 - 是否修改共享接口或契约：否 - 各子项目需要执行的验证：`python dev_scripts/check_harness.py --strict`、`python -m unittest discover -s tests -v` ## 原始需求 - 来源：用户对话 - 提出时间：2026-08-18 - 关键原话或脱敏摘要：用户要求「为了更加节省开发时间和 token，分析项目文件给出最小化方案」，并在两轮追问中要求只保留能确认真实节省的部分，最终确认「先做 B + E」。 ## 要解决什么 现状：AGENTS.md 开头写着「开始工作前先阅读[项目档案](docs/00-project-profile.md)」，这是一条无条件规则。docs/00-project-profile.md 约 2 100 tokens，且在每个新任务开始时都要重读一次，不命中 prompt cache。 实测该文件真正被高频使用的只有「常用命令」表（6 行）；其余章节（DevHarness 基线、子项目与交付单元、技术栈、目录边界、环境与凭据、项目专用验收要求）只在特定任务需要时才用得上。 目标：把高频的常用命令内联到 AGENTS.md，取消无条件读取，改为按需读取，减少每个任务的固定输入开销。 ## 做什么 / 不做什么 - 做：修改 AGENTS.md 的阅读入口规则；在 AGENTS.md 内联常用命令表；在 Wiki「开发工作流」中说明按需读取项目档案的触发条件。 - 不做：不删减 docs/00-project-profile.md 的任何内容；不改变项目档案作为事实来源的地位；不动 CLAUDE.md 的模型路由；不合并脚本入口（属另一工单）。 ## 已确认方案 1. AGENTS.md 开头规则由「开始工作前先阅读项目档案和任务涉及目录中的 AGENTS.md」改为：无条件只要求阅读任务涉及目录的 AGENTS.md；项目档案改为按需读取，并列出触发条件（需要环境与凭据、目录边界、子项目与交付单元划分、DevHarness 基线、项目专用验收要求时）。 2. 在 AGENTS.md 增加「常用命令」表，内联 check / test / sync / archive / export 命令，与项目档案保持一致。 3. Wiki「Development-Workflow」页对应说明同步更新；随后导出核心镜像。 不影响接口、数据库和安全边界。原有安全红线、门禁和验收要求一字不改。 预计修改文件： - AGENTS.md - Wiki 页面 Development-Workflow → 镜像 docs/01-workflow.md ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-18 | 由最初的「AGENTS.md 整体瘦身 + 项目档案按需读」缩减为只做「项目档案按需读 + 命令内联」 | 经核算，AGENTS.md 瘦身的节省会被 prompt cache 吸收，且需同步改动 check_harness.py 的 34 条字面校验，回本周期长 | 是 | ## 设计与原型门禁 - 修改类型：非 UI - 所需设计证据：架构、API、数据、状态或流程设计 - 可编辑设计源链接、版本或事实来源：本工单「已确认方案」一节 - 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，非 UI 改动 - 本地浏览方式和资源完整性检查：不适用 - 版本、revision 或确认日期：2026-08-18 - 状态：已确认 - 确认人、确认时间和覆盖范围：ila，2026-08-18，覆盖 AGENTS.md 阅读入口规则与常用命令表 - 无需 UI 原型或无需任何原型的原因：只修改 Agent 规则文本与文档，无任何用户界面 ## 文档影响 - [x] 更新项目档案或本地开发与验证 - [x] 更新其他 Wiki 页面：Development-Workflow ## 交付文档影响 - [x] 无交付文档影响，原因：本仓库为开发流程模板，无面向最终用户或其他岗位的交付文档受众变化 ## 验收标准 - [ ] AGENTS.md 不再包含「开始工作前先阅读项目档案」这类无条件要求，改为列出明确触发条件的按需读取 - [ ] AGENTS.md 内含常用命令表，且命令与 docs/00-project-profile.md 完全一致 - [ ] docs/00-project-profile.md 内容未被删改 - [ ] Wiki Development-Workflow 已更新并回读取得 revision，核心镜像已导出 - [ ] `python dev_scripts/check_harness.py --strict` 通过 - [ ] `python -m unittest discover -s tests -v` 通过 - [ ] `python dev_scripts/sync_wiki_docs.py --check` 通过 ## 验证方式 ```bash python dev_scripts/check_harness.py --strict python -m unittest discover -s tests -v python dev_scripts/sync_wiki_docs.py --check ``` 命令一致性由人工比对 AGENTS.md 与 docs/00-project-profile.md 的命令表确认。 ## 风险和回退 低风险。规则文本改动，不涉及接口、迁移、安全或不可逆操作。回退方式：`git revert` 对应实现提交，并把 Wiki Development-Workflow 恢复到本工单记录的前一版 revision。
ila commented 2026-08-18 21:28:18 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，状态：待验收

需求变化记录（补充）

日期 变化内容 原因 用户确认
2026-08-18 范围缩小：不修改任何 Wiki 页面 实施前核实「开始工作前先阅读项目档案」这条规则只存在于 AGENTS.md:5，Development-Workflow 页面未涉及，原计划的 Wiki 改动无对象 待确认（缩小范围，未改变已确认结果）

验收结果

验收标准 结果
AGENTS.md 不再包含无条件阅读项目档案的要求 通过
内联常用命令表且与项目档案一致 通过，命令集合 diff 为空
docs/00-project-profile.md 未被删改 通过，git diff 无输出
Wiki 更新并回读 revision，镜像已导出 不适用，经核实本任务无 Wiki 改动
check_harness.py --strict 通过
unittest discover -s tests -v 通过，Ran 40 tests，OK
sync_wiki_docs.py --check 通过，14 个核心镜像一致

证据

  • 实现提交：65ead42 refactor: 项目档案改为按需读取并内联常用命令 (#22)
  • 任务归档：Task-22-项目档案按需读取
  • 归档 revision：9ee818c20df172a369c7196f85754ac0fe767603
  • 未推送远端，等待验收。

未验证部分

规则文本改动无法自动验证「Agent 实际是否少读了项目档案」，需在后续任务中人工观察。

附带说明

行尾归一提交 a59dd19（新增 .gitattributes，43 个文件内容零变化）是独立的免工单格式化改动，不属于本工单范围。

## 实施完成，状态：待验收 ### 需求变化记录（补充） | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-18 | 范围缩小：不修改任何 Wiki 页面 | 实施前核实「开始工作前先阅读项目档案」这条规则只存在于 AGENTS.md:5，Development-Workflow 页面未涉及，原计划的 Wiki 改动无对象 | 待确认（缩小范围，未改变已确认结果） | ### 验收结果 | 验收标准 | 结果 | |---|---| | AGENTS.md 不再包含无条件阅读项目档案的要求 | 通过 | | 内联常用命令表且与项目档案一致 | 通过，命令集合 diff 为空 | | docs/00-project-profile.md 未被删改 | 通过，git diff 无输出 | | Wiki 更新并回读 revision，镜像已导出 | 不适用，经核实本任务无 Wiki 改动 | | `check_harness.py --strict` | 通过 | | `unittest discover -s tests -v` | 通过，Ran 40 tests，OK | | `sync_wiki_docs.py --check` | 通过，14 个核心镜像一致 | ### 证据 - 实现提交：`65ead42` refactor: 项目档案改为按需读取并内联常用命令 (#22) - 任务归档：Task-22-项目档案按需读取 - 归档 revision：`9ee818c20df172a369c7196f85754ac0fe767603` - 未推送远端，等待验收。 ### 未验证部分 规则文本改动无法自动验证「Agent 实际是否少读了项目档案」，需在后续任务中人工观察。 ### 附带说明 行尾归一提交 `a59dd19`（新增 .gitattributes，43 个文件内容零变化）是独立的免工单格式化改动，不属于本工单范围。
ila commented 2026-08-18 22:13:12 +08:00
Author
Owner
Copy Link
Copy Source

验收通过并关闭

  • 验收人：ila
  • 验收时间：2026-08-18
  • 归档页面：Task-22-项目档案按需读取
  • 归档 revision：dbb152565dd3（状态已置为已完成）
  • 实现提交：65ead42
  • 已推送：cdf83fd..bfdf648 → origin/main
  • 本工单无父 Epic / MVP，无需同步父工单。
  • 未导出 docs/task/ 快照；导出需用户明确提出。
## 验收通过并关闭 - 验收人：ila - 验收时间：2026-08-18 - 归档页面：Task-22-项目档案按需读取 - 归档 revision：`dbb152565dd3`（状态已置为已完成） - 实现提交：`65ead42` - 已推送：`cdf83fd..bfdf648` → origin/main - 本工单无父 Epic / MVP，无需同步父工单。 - 未导出 `docs/task/` 快照；导出需用户明确提出。
ila closed this issue 2026-08-18 22:13:15 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/dev_harness#22