容易踩的坑

下面几条能避开大多数“装了却感觉没用”或者“项目文件越来越乱”的情况。

以为装好 Trellis 后，所有项目自动生效

CLI 是全局安装，但每个项目仍要单独执行一次 trellis init --codex -u macdu。初始化后，项目内的 workflow、spec 和 skills 才存在。

初始化后不做 00-bootstrap

这会让 AI 读取通用模板，而不是你的真实项目规范。已有项目一定先校准；全新空项目先建最小骨架，再补 bootstrap。

每个小改动都 grill 很久

grill 用来解决模糊和取舍，不是所有任务的强制仪式。改字、改颜色、明确的小 bug 可以直接做；涉及业务边界、数据模型或重大交互时再用。

把 CONTEXT.md 当需求文档

CONTEXT.md 只放“术语是什么意思”，不写技术实现、任务计划和临时笔记。需求和验收条件放 Trellis 的 prd.md。

什么决定都写 ADR

只有同时满足三点才值得写：难以撤销、未来的人看不懂为什么这样做、确实比较过有代价的替代方案。普通样式选择和随时能改的小决定不用写。

Trellis 文件乱了就手工全删

先运行 trellis uninstall --dry-run 看清范围，再使用 trellis uninstall。不要直接删除混合了自定义内容的 AI 配置目录，以免误删自己的规则。

把“提交”和“推上去”当成一回事

commit 是保存在本地 Git 历史，push 才会上传 GitHub。涉及自动部署的项目，push 到监听分支后可能触发构建，所以最后一步要说清楚。

看见 hooks 提示就慌

Trellis 0.6.8 会提示 Codex hooks 需要在 Codex 配置中启用，并可能要通过 /hooks 批准。把提示原文交给 AI 检查配置即可；即使 hooks 暂时没生效，项目 skills 仍提供手动读取上下文的路线。

出问题时直接这样说

请检查当前项目的 Trellis 状态：
1. 读取 AGENTS.md 和 .trellis/workflow.md；
2. 运行 trellis platforms；
3. 检查项目 skills 和 Codex hooks 是否完整；
4. 保护已有用户改动；
5. 先报告问题和建议，不要直接覆盖或重装。

官方资料

本手册最后按本机 Trellis 0.6.8、实际 Codex 初始化结果以及已安装的 grill-with-docs、grilling、domain-modeling skills 核对。