#597·Trellis

项目级产品与架构文档 —— 任务归档后仍可持续沉淀与同步

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

  1. 需要查看时 grep 任务归档。 每个会话都重新拼全局图,任务数量增长后不可用,且没有任何机制保证摘要保持最新。
  2. 放进 .trellis/spec/ 语义不对:spec/ 被有意定义为"可执行的工程规范"(怎么写代码),不是产品/架构(是什么、为什么);且 .trellis/ 是隐藏目录,不适合人随时随手打开的文档。
  3. docs/ 但不与 Trellis 集成(现状)。 文档放 docs/ 本身是对的——但没有任何流程在规划时读它、在会话结束时更新它,结果就是静默腐烂。本 FR 只是为这类文件补上读/写挂钩。
  4. 用户自己改 workflow.md 今天就能做(workflow 文件允许本地定制),但每个用户都要重新发明这个步骤和文档,没有共享模板、没有 init 脚手架,跨平台、跨成员的行为会漂移。
  5. after_archive 生命周期 hook 自动同步。 不可行:hook 是 shell 命令,而"这个任务是否改变了产品/架构全局"需要 LLM 阅读任务工件才能判断——所以是 workflow 步骤(AI 驱动)而非 hook。