项目级产品与架构文档 —— 任务归档后仍可持续沉淀与同步
Author: jdjingdianCreated Sep 2, 2026Updated Sep 8, 2026
Labelsenhancementpkg:cli
Feature Description
Trellis 目前维护三层知识:
| 层 | 回答的问题 | 生命周期 |
|---|---|---|
.trellis/spec/ |
代码怎么写(工程规范、契约) | 永久 |
.trellis/tasks/<task>/prd.md + design.md |
这个任务做什么、为什么 | 归档进 archive/YYYY-MM/ 后即失效 |
.trellis/workspace/ |
发生了什么(会话日志) | 2000 行后轮转 |
我作为一个个人开发者,基本所有项目都喜欢用 trellis。但是我不是一个专业的产品经理,多个项目并行并迭代一段时间后,我可能就会对某个项目的架构、需求情况丢失记忆,代码又不是我写的,对内部细节就更不清楚了。
倾向方案
在仓库内一个可见的、人随时方便打开的位置(建议 docs/product.md + docs/architecture.md;单文件根目录 PROJECT.md 也可以——命名与位置开放给 maintainer 定)增加两份 living 文档:
- 产品文档 — 产品定位、目标用户、当前能力地图、产品决策日志。
- 架构文档 — 系统结构、模块地图、关键数据流、关键技术决策(ADR 式:每条 = 一行结论 + 日期 + 指向来源任务归档
design.md的路径),配合 ASCII BOX 和 MERMAID 流程图说明。
在每个任务结束,比如 finish-work 的时候,同步更新一下上述的文档,这样我可以随时打开查看项目的全貌。
Motivation
任务滚动几个月后,没有任何一个地方能回答"这个系统是什么、今天能做什么、当初为什么这么决定"——答案散落在几十个归档任务目录里,不启动新的 agent 会话时,我很难再去理解我做的项目(山)
Alternatives Considered
- 需要查看时 grep 任务归档。 每个会话都重新拼全局图,任务数量增长后不可用,且没有任何机制保证摘要保持最新。
- 放进
.trellis/spec/。 语义不对:spec/被有意定义为"可执行的工程规范"(怎么写代码),不是产品/架构(是什么、为什么);且.trellis/是隐藏目录,不适合人随时随手打开的文档。 - 纯
docs/但不与 Trellis 集成(现状)。 文档放docs/本身是对的——但没有任何流程在规划时读它、在会话结束时更新它,结果就是静默腐烂。本 FR 只是为这类文件补上读/写挂钩。 - 用户自己改
workflow.md。 今天就能做(workflow 文件允许本地定制),但每个用户都要重新发明这个步骤和文档,没有共享模板、没有init脚手架,跨平台、跨成员的行为会漂移。 after_archive生命周期 hook 自动同步。 不可行:hook 是 shell 命令,而"这个任务是否改变了产品/架构全局"需要 LLM 阅读任务工件才能判断——所以是 workflow 步骤(AI 驱动)而非 hook。
Source: mindfold-ai/Trellis