project-knowledge-harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

project-knowledge-harness

项目知识管理工具

A lightweight, file-based memory harness for any software project.

Three surfaces, sharply separated by time direction and access pattern:

Surface	Time	Question it answers	Access pattern
`TODO.md`	Future	"What might we do later?"	Read top to bottom (priority lanes)
`backlog/<slug>.md`	Future	"What was the analysis behind this idea?"	Indexed from `TODO.md`
`pitfalls/<slug>.md`	Past	"I see error X — has this happened before?"	Grep symptom keywords

Plus, in projects that already have agent contracts,

AGENTS.md

Hard invariants answer "What rules MUST agents follow?". Pitfalls graduate to Hard invariants when serious enough — see

references/when-to-add-docs.md

一个适用于任意软件项目的轻量级、基于文件的记忆管理体系。

三个核心模块，按时间维度和访问模式明确区分：

模块	时间维度	解决的问题	访问模式
`TODO.md`	未来	"我们之后可能要做什么？"	从上到下阅读（按优先级分区）
`backlog/<slug>.md`	未来	"这个想法背后的分析依据是什么？"	从 `TODO.md` 索引跳转
`pitfalls/<slug>.md`	过去	"我遇到了错误X——之前发生过吗？"	通过症状关键词grep检索

此外，对于已存在Agent契约的项目，

AGENTS.md

中的硬规则用于回答"Agent必须遵循哪些规则？"。当问题陷阱足够严重时，会升级为硬规则——详见

references/when-to-add-docs.md

。

When to use this skill

何时使用该工具

Use this skill when the user surfaces any of:

A long-term TODO list with no home, or a messy
```
TODO.md
```
that needs structure (signals: "where should ideas go?", "maybe later", "工程量太大需要再評估")
A debugging session worth saving (signals: "keep solving the same problem twice", "save this troubleshooting", "踩過的坑", "TROUBLESHOOTING.md scattered across docs/")
A request to consolidate
```
IDEAS.md
```
/
```
ROADMAP.md
```
/
```
WISHLIST.md
```
/
```
LESSONS.md
```
files

Do NOT use this skill for active sprint planning (use issue trackers), ephemeral agent scratchpads (use

.claude/plans/

), or current feature documentation (use

docs/

当用户出现以下任一需求时，即可使用该工具：

长期待办事项列表无合适存储位置，或
```
TODO.md
```
杂乱无章需要结构化整理（信号："想法应该存在哪里？"、"以后再考虑"、"工程量太大需要再评估"）
值得留存的调试会话（信号："重复解决同一问题"、"保存本次故障排查记录"、"踩过的坑"、"TROUBLESHOOTING.md分散在docs/目录下"）
需要合并
```
IDEAS.md
```
/
```
ROADMAP.md
```
/
```
WISHLIST.md
```
/
```
LESSONS.md
```
等文件的请求

请勿将该工具用于：活跃的迭代规划（使用问题追踪器）、Agent临时草稿（使用

.claude/plans/

）、当前功能文档（使用

docs/

）。

How to apply this skill (default workflow)

如何使用该工具（默认工作流）

The skill bundles five scripts and several templates. Default to the init script for setup, and default to
add-todo.sh
/
sweep-inbox.sh
for capture rather than asking the agent to edit

TODO.md

by hand.

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

该工具包含5个脚本和多个模板。默认使用init脚本完成初始化，默认使用
add-todo.sh
/
sweep-inbox.sh
记录内容，而非手动编辑

TODO.md

。

scripts/
  init.sh         # 一键搭建 TODO.md + backlog/ + pitfalls/
                  # + Agent指引 + README片段
  todo-kanban.sh  # 验证TODO.md格式并渲染看板样式视图
  add-todo.sh     # 将结构化条目插入对应的## P*分区
  promote-todo.sh # 将活跃的TODO项移动到## Done分区，使用正确语法
  sweep-inbox.sh  # 通过add-todo.sh将backlog/inbox.md中的内容分类整理到TODO.md

1. Run

scripts/init.sh

against the target repo

1. 针对目标仓库运行

scripts/init.sh

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

The script:

Creates

TODO.md

backlog/README.md

pitfalls/README.md

from

assets/*.template

, substituting placeholders.

Appends an agent-guidance snippet to
```
AGENTS.md
```
/
```
CLAUDE.md
```
(auto-detected, override with
```
--agent-contract
```
).
Appends a "Roadmap & lessons learned" section to
```
README.md
```
.

Runs

scripts/todo-kanban.sh --validate-only TODO.md

so any drift is caught immediately.

Prints the deployment-exclusion lines you should add manually (it does not edit ignore files — see
```
references/deployment-exclusion.md
```
).

init.sh

is idempotent: existing files are skipped unless

--force

is given, and snippets append only if a sentinel marker is missing.

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

该脚本会执行以下操作：

从

assets/*.template

创建

TODO.md

、

backlog/README.md

、

pitfalls/README.md

，替换占位符内容。

将Agent指引片段追加到
```
AGENTS.md
```
/
```
CLAUDE.md
```
（自动检测，可通过
```
--agent-contract
```
覆盖）。
将"路线图与经验总结"部分追加到
```
README.md
```
。

运行

scripts/todo-kanban.sh --validate-only TODO.md

，立即捕获任何格式偏差。

打印需手动添加的部署排除规则（不会自动编辑忽略文件——详见
```
references/deployment-exclusion.md
```
）。

init.sh

是幂等的：除非添加

--force

参数，否则会跳过已存在的文件；只有当标记不存在时，才会追加片段内容。

2. Mid-conversation, when the user surfaces a "maybe later" idea

2. 对话过程中，当用户提出「以后再考虑」的想法时

Signals: "maybe later", "nice to have", "if I'm interested", "工程量太大需要再評估", "先記下來", "not now but…".

If
```
TODO.md
```
doesn't exist yet, run
```
scripts/init.sh
```
first.
Default path — call
scripts/add-todo.sh
with the priority, effort, title, and description. This inserts the canonical line into the right
```
## P*
```
lane and re-validates. Add
```
--backlog
```
if the conversation produced enough investigation that a
```
backlog/<slug>.md
```
doc is worth scaffolding.
sh
```
scripts/add-todo.sh --priority "P?" --effort M \
  --title "Try Rspress for docs" \
  --description "Evaluate AI-native docs framework alternative"
```
Quick-capture path — append to
backlog/inbox.md
when the user isn't sure of priority/effort yet, or is mid-thought:
sh
```
echo "- $UNSTRUCTURED_THOUGHT" >> backlog/inbox.md
```
Later (this session or next), run
```
scripts/sweep-inbox.sh
```
to formalize the loose lines into
```
TODO.md
```
one at a time. The sweeper prompts for missing fields per line; in
```
--batch
```
mode it only processes lines that already have
```
priority=… effort=… title="…" description="…"
```
pairs and leaves ambiguous ones in place.
Manual edit path — only when scripts can't help. Use the syntax from
```
references/tag-schema.md
```
and run
```
scripts/todo-kanban.sh --validate-only
```
afterwards.
If you wrote a
```
backlog/<slug>.md
```
(either via
```
--backlog
```
or by hand), make sure the TODO line ends with
```
 → [research](backlog/<slug>.md)
```
so the index points to the doc.

信号："以后再考虑"、"锦上添花的功能"、"如果我感兴趣的话"、"工程量太大需要再评估"、"先记下来"、"现在不做但…"。

如果
```
TODO.md
```
尚未存在，先运行
```
scripts/init.sh
```
。
默认流程——调用
scripts/add-todo.sh
，传入优先级、工作量、标题和描述。该脚本会将标准条目插入对应的
```
## P*
```
分区并重新验证格式。如果对话中产生了足够多的调研内容，值得生成
```
backlog/<slug>.md
```
文档，则添加
```
--backlog
```
参数。
sh
```
scripts/add-todo.sh --priority "P?" --effort M \
  --title "Try Rspress for docs" \
  --description "Evaluate AI-native docs framework alternative"
```
快速记录流程——追加到
backlog/inbox.md
，当用户不确定优先级/工作量，或正处于思考过程中时使用：
sh
```
echo "- $UNSTRUCTURED_THOUGHT" >> backlog/inbox.md
```
之后（本次会话或下次会话），运行
```
scripts/sweep-inbox.sh
```
将零散的条目逐一整理到
```
TODO.md
```
中。整理工具会逐行提示补充缺失的字段；在
```
--batch
```
模式下，仅处理已包含
```
priority=… effort=… title="…" description="…"
```
的条目，将模糊的条目保留在原文件中。
手动编辑流程——仅在脚本无法处理时使用。使用
```
references/tag-schema.md
```
中的语法，之后运行
```
scripts/todo-kanban.sh --validate-only
```
验证格式。
如果生成了
```
backlog/<slug>.md
```
（通过
```
--backlog
```
参数或手动创建），确保TODO条目末尾包含
```
 → [research](backlog/<slug>.md)
```
，以便索引指向该文档。

3. Mid-conversation, when you finish debugging something tricky

3. 对话过程中，当完成复杂的故障排查时

Signals: "phew, that took a while", "weird, the error didn't say anything about X", "this is the third time we've hit this", or you find yourself reconstructing context that isn't in any doc.

Create
```
pitfalls/<symptom-slug>.md
```
immediately from
```
assets/pitfall-doc.md.template
```
, while the trace is fresh. Title the doc by the symptom, not the root cause — you'll search by what you're seeing, not by what you eventually learned.
Copy verbatim error messages — never paraphrase, it kills grep-ability.
If the trap is severe (silent corruption / cross-machine recurrence / non-obvious workaround), surface it: "should this graduate to a Hard invariant in AGENTS.md?" — see
```
references/when-to-add-docs.md
```
.

信号："呼，终于搞定了"、"奇怪，错误信息完全没提到X"、"这是第三次遇到这个问题了"，或是你发现自己正在重构文档中未记录的上下文。

立即从
```
assets/pitfall-doc.md.template
```
创建
```
pitfalls/<symptom-slug>.md
```
，趁记忆清晰时记录。文档标题应以症状命名，而非根本原因——你会根据当前看到的现象搜索，而非最终发现的原因。
直接复制错误信息——切勿改写，否则会破坏grep检索能力。
如果问题陷阱非常严重（静默数据损坏/跨机器复现/非直观的解决方案），请提出："是否应将其升级为AGENTS.md中的硬规则？"——详见
```
references/when-to-add-docs.md
```
。

4. When implementing a

TODO.md

item

4. 当实现

TODO.md

中的条目时

In the same commit:

Run
```
scripts/promote-todo.sh --title "<substring>" --summary "<what shipped>"
```
. It removes the active line and inserts the dated
```
Done
```
entry, then re-validates. It refuses to run if the substring matches zero or more than one active item.
If a
```
backlog/<slug>.md
```
exists, set its
```
Status: shipped
```
(don't delete — historical record may inform adjacent decisions).
If shipping uncovered a trap, write a
```
pitfalls/<slug>.md
```
for it.

在同一个提交中：

运行
```
scripts/promote-todo.sh --title "<substring>" --summary "<what shipped>"
```
。该脚本会移除活跃条目并插入带日期的
```
Done
```
条目，然后重新验证格式。如果子字符串匹配0个或多个活跃条目，脚本会拒绝执行。
如果存在
```
backlog/<slug>.md
```
，将其
```
Status
```
设置为
```
shipped
```
（请勿删除——历史记录可能为相关决策提供参考）。
如果发布过程中发现新的问题陷阱，编写对应的
```
pitfalls/<slug>.md
```
。

When a TODO entry needs a

backlog/

doc, when a debug needs a

pitfalls/

doc

何时为TODO条目创建

backlog/

文档，何时为调试记录创建

pitfalls/

文档

Decision rules and the upgrade path to

AGENTS.md

invariants live in

references/when-to-add-docs.md

. Read it the first time you set up the harness; consult it again whenever you're unsure which surface a piece of knowledge belongs in.

决策规则以及升级为

AGENTS.md

硬规则的路径详见

references/when-to-add-docs.md

。首次搭建该管理体系时请阅读；每当不确定某条知识应归属哪个模块时，可再次查阅。

Tag schema

标签 schema

Two orthogonal axes, validated by

scripts/todo-kanban.sh

. See

references/tag-schema.md

for the full schema, useful tag combinations, and the exact validator-checked syntax.

两个正交维度，由

scripts/todo-kanban.sh

验证。完整schema、实用标签组合以及验证器检查的精确语法详见

references/tag-schema.md

。

Anti-patterns

反模式

Common mistakes to avoid (e.g., spawning

IDEAS.md

alongside

TODO.md

, titling pitfalls by root cause, paraphrasing errors). Full list in

references/anti-patterns.md

需避免的常见错误（例如：在

TODO.md

之外创建

IDEAS.md

、以根本原因命名问题陷阱文档、改写错误信息）。完整列表详见

references/anti-patterns.md

。

Deployment exclusion

部署排除规则

TODO.md

backlog/

, and

pitfalls/

are maintainer-facing repo metadata, not files to ship. Cheatsheet for chezmoi / npm / pip / Docker in

references/deployment-exclusion.md

scripts/init.sh --deployment ...

prints the exact lines to add.

TODO.md

、

backlog/

和

pitfalls/

是面向维护者的仓库元数据，不属于发布文件。针对chezmoi / npm / pip / Docker的速查表详见

references/deployment-exclusion.md

。

scripts/init.sh --deployment ...

会打印需添加的精确规则。

Templates and bundled assets

模板与内置资源

```
assets/TODO.md.template
```
—
```
TODO.md
```
skeleton with example items per lane

assets/backlog-README.md.template

—

backlog/

index + when-to-add rules

```
assets/backlog-doc.md.template
```
— single backlog doc (context-first)
```
assets/pitfalls-README.md.template
```
—
```
pitfalls/
```
index + cross-reference table for traps documented elsewhere
```
assets/pitfall-doc.md.template
```
— single pitfall doc (symptom-first)

assets/agent-guidance.md.template

— snippet for

AGENTS.md

CLAUDE.md

assets/readme-roadmap.md.template

— snippet for project

README.md

```
scripts/init.sh
```
— one-shot setup
```
scripts/todo-kanban.sh
```
— validator + Markdown kanban renderer (also supports
```
--json
```
and
```
--validate-only
```
)

scripts/add-todo.sh

— structured insert into

## P*

lane;

--backlog

also scaffolds

backlog/<slug>.md

```
scripts/promote-todo.sh
```
— atomic active-→-Done move with re-validation

scripts/sweep-inbox.sh

— triage

backlog/inbox.md

→

add-todo.sh

```
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

的片段

```
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

Reference implementation

参考实现

A live example of this harness is at

daviddwlee84/dotfiles

```
TODO.md
```
,
```
backlog/
```
,
```
pitfalls/
```
directories at repo root

AGENTS.md

### Long-term backlog → TODO.md + backlog/

and

### Past pitfalls → pitfalls/

sections

```
README.md
```
```
## Roadmap & lessons learned
```
section

该管理体系的实际示例位于

daviddwlee84/dotfiles

：

仓库根目录下的
```
TODO.md
```
、
```
backlog/
```
、
```
pitfalls/
```
目录

AGENTS.md

中的

### Long-term backlog → TODO.md + backlog/

和

### Past pitfalls → pitfalls/

章节

```
README.md
```
中的
```
## Roadmap & lessons learned
```
章节

project-knowledge-harness

Original

Translation

project-knowledge-harness

项目知识管理工具

When to use this skill

何时使用该工具

How to apply this skill (default workflow)

如何使用该工具（默认工作流）

1. Run
`scripts/init.sh`
against the target repo

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

2. Mid-conversation, when the user surfaces a "maybe later" idea

2. 对话过程中，当用户提出「以后再考虑」的想法时

3. Mid-conversation, when you finish debugging something tricky

3. 对话过程中，当完成复杂的故障排查时

4. When implementing a
`TODO.md`
item

4. 当实现
`TODO.md`
中的条目时

When a TODO entry needs a
`backlog/`
doc, when a debug needs a
`pitfalls/`
doc

何时为TODO条目创建
`backlog/`
文档，何时为调试记录创建
`pitfalls/`
文档

Tag schema

标签 schema

Anti-patterns

反模式

Deployment exclusion

部署排除规则

Templates and bundled assets

模板与内置资源

Reference implementation

参考实现

project-knowledge-harness

Original

Translation

project-knowledge-harness

项目知识管理工具

When to use this skill

何时使用该工具

How to apply this skill (default workflow)

如何使用该工具（默认工作流）

1. Run scripts/init.sh against the target repo

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

2. Mid-conversation, when the user surfaces a "maybe later" idea

2. 对话过程中，当用户提出「以后再考虑」的想法时

3. Mid-conversation, when you finish debugging something tricky

3. 对话过程中，当完成复杂的故障排查时

4. When implementing a TODO.md item

4. 当实现TODO.md中的条目时

When a TODO entry needs a backlog/ doc, when a debug needs a pitfalls/ doc

何时为TODO条目创建backlog/文档，何时为调试记录创建pitfalls/文档

Tag schema

标签 schema

Anti-patterns

反模式

Deployment exclusion

部署排除规则

Templates and bundled assets

模板与内置资源

Reference implementation

参考实现

1. Run
`scripts/init.sh`
against the target repo

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

4. When implementing a
`TODO.md`
item

4. 当实现
`TODO.md`
中的条目时

When a TODO entry needs a
`backlog/`
doc, when a debug needs a
`pitfalls/`
doc

何时为TODO条目创建
`backlog/`
文档，何时为调试记录创建
`pitfalls/`
文档