用途：在完成一次调试、实现或讨论后，把有价值的知识沉淀为可执行的代码规范（code-spec），而不是仅写原则性文字。Trellis 在实现工作中所说的 spec 指 code-spec：可执行契约、具体签名、载荷字段、环境变量键、边界行为，以及可测试的校验与错误行为。
何时更新：新增或修改命令、API 签名，跨层请求/响应契约变更，数据库模式或迁移变更，基础设施集成（存储、队列、缓存、密钥、环境接线）时，必须写足 code-spec 深度。强制输出包含七部分：范围/触发、签名（命令/API/数据库）、契约（请求/响应/环境）、校验与错误矩阵、Good/Base/Bad 案例、所需测试（含断言点）、至少一对错误与正确写法。
目录结构：.trellis/spec/<layer>/.md 为各层编码规范，guides/.md 为思考清单。判断规则：写代码方式放 spec 层目录，写代码前要考虑什么放 guides。guides 应短小并指向 spec，不重复规则。
更新流程：先明确学到什么、为什么重要、属于哪个 spec；再分类（设计决策、项目约定、新模式、禁止模式、常见错误、Gotcha）；编辑前先读目标 spec 避免重复；更新要具体、解释原因、展示契约与代码片段、一节一个概念；必要时更新 index.md。
典型触发场景：实现功能后、修复 bug 后、发现新模式后、定下约定后，把结论写入对应 spec 章节（Design Decisions、Patterns、Anti-patterns、Common Mistakes 等），并附代码示例。
与其他命令关系：break-loop 深入分析 bug 常会暴露需更新的 spec，finish-work 提醒检查 spec 是否需要更新。核心是持续积累可复用的实现契约。限制：资料未提供平台、收费、安装方式等信息。