project-knowledge-harness

project-knowledge-harness

适用于任何软件项目的轻量级文件式记忆工具集。

三个界面按时间方向和访问模式清晰区分：

界面	时间	回答的问题	访问模式
TODO.md	未来	“之后我们可能会做什么？”	从上到下阅读（按优先级划分）
backlog/<slug>.md	未来	“这个想法背后的分析是什么？”	从 TODO.md 索引
pitfalls/<slug>.md	过去	“我遇到了错误 X——以前发生过这种情况吗？”	搜索症状关键词

此外，在已有 Agent 约定的项目中，AGENTS.md 中的硬性约束会回答“Agent 必须遵守哪些规则？”。严重到一定程度的陷阱会升级为硬性约束——请参阅 references/when-to-add-docs.md。

何时使用此技能

当用户提出以下任何需求时，请使用此技能：

• 长期 TODO 列表无处安放，或杂乱的 TODO.md 需要整理（信号：“想法该放在哪里？”，“以后再说”，“工程量太大需要再評估”）
• 值得记录的调试过程（信号：“同一个问题反复解决”，“保存这次故障排查”，“踩過的坑”，“分散在 docs/ 中的 TROUBLESHOOTING.md”）
• 请求整合 IDEAS.md / ROADMAP.md / WISHLIST.md / LESSONS.md 文件

请勿将此技能用于当前冲刺规划（使用 Issue 跟踪器，或使用 td 管理进行中的 Agent 工作——请参阅下文的“可选：td 集成”）、临时 Agent 草稿（使用 .claude/plans/），或当前功能文档（使用 docs/）。

如何应用此技能（默认工作流）

此技能包含六个脚本和多个模板。设置时默认使用初始化脚本；记录内容时，默认使用 add-todo.sh / sweep-inbox.sh，而不是要求 Agent 手动编辑 TODO.md。

scripts/
  init.sh         # one-shot setup of TODO.md + backlog/ + pitfalls/
                  # + agent guidance + README snippet
  todo-kanban.sh  # validate TODO.md format and render kanban-style board
  add-todo.sh     # insert a structured entry into the right ## P* lane
  promote-todo.sh # move an active TODO item to ## Done with the right syntax
  sweep-inbox.sh  # triage backlog/inbox.md into TODO.md via add-todo.sh
  start-todo.sh   # optional: open/reuse a td issue for an item (no-op without td)
  _lib/           # shared TODO parser + td bridge (sourced, not run directly)

1. 对目标仓库运行 scripts/init.sh

scripts/init.sh \
  --target /path/to/project \
  --project-name "My Project" \
  --deployment chezmoi   # or npm | pip | docker | none

该脚本会：

1. 根据 assets/*.template 创建 TODO.md、backlog/README.md 和 pitfalls/README.md，并替换其中的占位符。
2. 将 Agent 指引片段追加到 AGENTS.md / CLAUDE.md（自动检测，也可通过 --agent-contract 覆盖）。
3. 将“路线图与经验教训”一节追加到 README.md。
4. 运行 scripts/todo-kanban.sh --validate-only TODO.md，以便立即发现任何偏差。
5. 输出应由你手动添加的部署排除规则（不会修改忽略文件——请参阅 references/deployment-exclusion.md）。

init.sh 具有幂等性：除非指定 --force，否则会跳过现有文件；只有在缺少哨兵标记时，才会追加片段。

2. 对话进行中，用户提出“以后再说”的想法时

信号：“以后再说”“锦上添花”“如果我感兴趣”， “工程量太大需要再評估”“先記下來”“现在不做，不过……”。

1. 如果 TODO.md 尚不存在，先运行 scripts/init.sh。

2. 默认路径——调用 scripts/add-todo.sh，并提供优先级、 工作量、标题和描述。这会将规范条目插入正确的 ## P* 区段， 并重新验证。如果对话中进行了足够多的调查，值得为 backlog/<slug>.md 文档搭建框架，则添加 --backlog。

   scripts/add-todo.sh --priority "P?" --effort M \
     --title "Try Rspress for docs" \
     --description "Evaluate AI-native docs framework alternative"
   

3. 快速记录路径——追加到 backlog/inbox.md，适用于用户 尚未确定优先级／工作量，或还在思考的情况：

   echo "- $UNSTRUCTURED_THOUGHT" >> backlog/inbox.md
   

   之后（本次会话或下次会话），运行 scripts/sweep-inbox.sh， 逐条将这些未整理的条目正式写入 TODO.md。清理脚本会逐条提示 缺失字段；在 --batch 模式下，它只处理已包含 priority=… effort=… title="…" description="…" 字段对的条目，并保留含糊不清的条目。

4. 手动编辑路径——仅在脚本无法帮忙时使用。 使用 references/tag-schema.md 中的语法，并在之后运行 scripts/todo-kanban.sh --validate-only。

5. 如果你编写了 backlog/<slug>.md（通过 --backlog 或手动编写）， 请确保 TODO 条目以 → [research](backlog/<slug>.md) 结尾，这样索引才能指向该文档。

3. 对话进行中，棘手问题调试完成时

信号：“呼，花了好一阵子”“奇怪，错误信息里完全没提到 X” “这已经是第三次遇到这种情况了”，或者你发现自己正在重建任何文档 都没有记录的上下文。

1. 趁过程还记忆犹新，立即使用 assets/pitfall-doc.md.template 创建 pitfalls/<symptom-slug>.md。 文档标题应写症状，而不是根本原因——你会按眼前看到的情况 搜索，而不是按最终了解到的原因搜索。
2. 原样复制错误信息——切勿转述，否则会导致 grep 难以查找。
3. 如果这个陷阱很严重（静默数据损坏／在多台机器上反复出现／ 解决方法不明显），请提出：“是否应将其提升为 AGENTS.md 中的 Hard invariant？”——参见 references/when-to-add-docs.md。

4. 实现 TODO.md 项目时

在同一个提交中：

1. 运行 scripts/promote-todo.sh --title "<substring>" --summary "<what shipped>"。 它会移除活跃条目并插入带日期的 Done 条目，然后重新验证。 如果子字符串匹配到零个或多个活跃项目，它会拒绝运行。
2. 如果存在 backlog/<slug>.md，将其 Status: shipped（不要 删除——历史记录可能为相关决策提供参考）。
3. 如果发布过程中发现了陷阱，为其编写 pitfalls/<slug>.md。

可选：td 集成

如果项目使用 td 管理进行中的 Agent 工作， 这些脚本会检测它（PKH_TD=auto|on|off，默认值为 auto），并进行单向桥接。 Git 始终是真实信息源。标记为 pkh 且标题相同的 td 问题会指向其 TODO.md 条目，而 TODO.md 从不保存 td id，因为这些 id 仅在本机有效。

• 开始处理项目：scripts/start-todo.sh --title "<substring>" 会创建或 复用 td 问题，并开始处理。
• promote-todo.sh 随后会打印一条提示，建议先收集信息再进行审查，但绝不会关闭 问题。todo-kanban.sh 会标记进行中的项目，并列出孤立的问题。
• 如果存在 td，init.sh 会将路由代码片段追加到 Agent 合约中。
• “以后再说”的想法仍应交给 add-todo.sh，而不是 td create／td defer。

不使用 td 时，不会有任何变化。分层方式、多机注意事项、td 退出 计划，以及 GitHub Issues／Linear 使用指南，参见 references/integrating-trackers.md。

何时需要为 TODO 条目添加 backlog/ 文档，何时需要为调试问题添加 pitfalls/ 文档

关于决策规则以及将知识升级为 AGENTS.md 不变量的路径，请参阅 references/when-to-add-docs.md。首次设置工具链时请阅读此文档；每当你不确定某条知识应归入哪个部分时，也请再次查阅。

标签模式

两个相互独立的维度，由 scripts/todo-kanban.sh 验证。完整模式、 实用的标签组合以及验证器检查的确切语法，请参阅 references/tag-schema.md。

反模式

应避免的常见错误（例如，在 TODO.md 旁边新增 IDEAS.md、 按根本原因为陷阱命名、转述错误信息）。完整列表请参阅 references/anti-patterns.md。

部署排除

TODO.md、backlog/ 和 pitfalls/ 是面向维护者的仓库元数据， 不是要随产品发布的文件。有关 chezmoi / npm / pip / Docker 的速查指南，请参阅 references/deployment-exclusion.md。 scripts/init.sh --deployment ... 会输出需要添加的确切行。

模板和捆绑资源

• assets/TODO.md.template — TODO.md 骨架，包含每个泳道的示例条目
• assets/backlog-README.md.template — backlog/ 索引及何时添加文档的规则
• assets/backlog-doc.md.template — 单篇待办文档（优先提供上下文）
• assets/pitfalls-README.md.template — pitfalls/ 索引及交叉引用表，列出在其他位置记录的陷阱
• assets/pitfall-doc.md.template — 单篇陷阱文档（优先描述症状）
• assets/agent-guidance.md.template — 用于 AGENTS.md / CLAUDE.md 的片段
• assets/readme-roadmap.md.template — 用于项目 README.md 的片段
• assets/td-routing.md.template — td ↔ TODO.md 路由片段 （检测到 td 时由 init.sh 追加）
• scripts/init.sh — 一次性设置
• scripts/todo-kanban.sh — 验证器 + Markdown 看板渲染器 （也支持 --json 和 --validate-only）
• scripts/add-todo.sh — 向 ## P* 泳道中结构化插入条目； --backlog 还会创建 backlog/<slug>.md 骨架
• scripts/promote-todo.sh — 原子地将进行中的条目移至 Done，并重新验证
• scripts/sweep-inbox.sh — 将 backlog/inbox.md 中的条目分流至 add-todo.sh
• scripts/start-todo.sh — 可选的 td 桥接：将条目作为 td 问题启动
• scripts/_lib/todo-match.sh、scripts/_lib/td-bridge.sh — 共用辅助脚本

参考实现

此工具链的实际示例见 daviddwlee84/dotfiles：

• 仓库根目录下的 TODO.md、backlog/、pitfalls/ 目录
• AGENTS.md 中的 ### Long-term backlog → TODO.md + backlog/ 和 ### Past pitfalls → pitfalls/ 章节
• README.md 中的 ## Roadmap & lessons learned 章节