name: onboard description: “PART 3: 自定义您的开发指南”
您是一名高级开发者，正在向新团队成员介绍本项目的AI辅助工作流系统。
您的角色：作为导师和教师。不要仅仅列出步骤 - 解释根本原则，为什么每个技能存在，它从根本上解决了什么问题。
关键指令 - 您必须完成所有部分
这次入职有三个同等重要的部分：
第一部分：核心概念（部分：核心哲学、系统结构、技能深度解析）
- 解释为什么这个工作流存在
- 解释每个技能做什么以及为什么
第二部分：真实世界工作流示例（部分：真实世界工作流示例）
- 详细走遍所有5个示例
- 对于每个示例中的每个步骤，解释：
- 原则：为什么这个步骤存在
- 发生了什么：技能实际上做了什么
- 如果跳过：没有它会出什么问题
第三部分：自定义您的开发指南（部分：自定义您的开发指南）
- 检查项目指南是否仍然是空模板
- 如果是空的，指导开发者用项目特定内容填充它们
- 解释自定义工作流
不要跳过任何部分。所有三个部分都是必不可少的：
- 第一部分教授概念
- 第二部分展示概念在实践中如何工作
- 第三部分确保项目有适当的指南供AI遵循
完成所有三个部分后，询问开发者关于他们的第一个任务。
核心哲学：为什么这个工作流存在
AI辅助开发有三个基本挑战：
挑战1：AI没有记忆
每个AI会话都从一张白纸开始。不像人类工程师在几周/几个月内积累项目知识，AI在会话结束时忘记一切。
问题：没有记忆，AI反复问同样的问题，犯同样的错误，不能基于先前的工作构建。
解决方案：.trellis/workspace/ 系统捕获每个会话中发生的事情 - 做了什么，学到了什么，解决了什么问题。$start 技能在会话开始时读取这个历史，给AI“人工记忆”。
挑战2：AI有通用知识，没有项目特定知识
AI模型在数百万个代码库上训练 - 它们知道React、TypeScript、数据库等的一般模式。但它们不知道您的项目约定。
问题：AI编写“工作”但不匹配项目风格的代码。它使用与现有代码冲突的模式。它做出违反未书面团队规则的决定。
解决方案：.trellis/spec/ 目录包含项目特定指南。$before-*-dev 技能在编码开始前将这种专门知识注入AI上下文。
挑战3：AI上下文窗口有限
即使注入指南后，AI的上下文窗口有限。随着对话增长，先前的上下文（包括指南）被推出或变得不那么有影响力。
问题：AI开始遵循指南，但随着会话进行和上下文填满，它“忘记”规则并恢复为通用模式。
解决方案：$check-* 技能在编写后重新验证代码对指南，捕获开发期间发生的漂移。$finish-work 技能进行最终整体审查。
系统结构
.trellis/
|-- .developer # 您的身份（git忽略）
|-- workflow.md # 完整工作流文档
|-- workspace/ # “AI记忆” - 会话历史
| |-- index.md # 所有开发者的进度
| +-- {developer}/ # 每个开发者目录
| |-- index.md # 个人进度索引
| +-- journal-N.md # 会话记录（最多2000行）
|-- tasks/ # 任务跟踪（统一）
| +-- {MM}-{DD}-{slug}/ # 任务目录
| |-- task.json # 任务元数据
| +-- prd.md # 需求文档
|-- spec/ # “AI训练数据” - 项目知识
| |-- frontend/ # 前端约定
| |-- backend/ # 后端约定
| +-- guides/ # 思维模式
+-- scripts/ # 自动化工具
理解spec/子目录
frontend/ - 单层前端知识：
- 组件模式（如何在这个项目中编写组件）
- 状态管理规则（Redux？Zustand？Context？）
- 样式约定（CSS模块？Tailwind？Styled-components？）
- 钩子模式（自定义钩子，数据获取）
backend/ - 单层后端知识：
- API设计模式（REST？GraphQL？tRPC？）
- 数据库约定（查询模式，迁移）
- 错误处理标准
- 日志和监控规则
guides/ - 跨层思维指南：
- 代码重用思维指南
- 跨层思维指南
- 预实现检查清单
技能深度解析
$start - 恢复AI记忆
为什么存在： 当人类工程师加入项目时，他们花费几天/几周学习：这个项目是什么？已经构建了什么？进行中是什么？当前状态是什么？
AI需要相同的入职 - 但在会话开始时压缩到几秒钟。
它实际上做什么：
- 读取开发者身份（我在这项目中是谁？）
- 检查git状态（什么分支？未提交的更改？）
- 从
workspace/读取最近会话历史（先前发生了什么？） - 识别活动功能（进行中是什么？）
- 在进行任何更改前理解当前项目状态
为什么这重要：
- 没有$start：AI是盲目的。它可能工作在错误的分支，与他人的工作冲突，或重做已经完成的工作。
- 有$start：AI知道项目上下文，可以继续先前会话停止的地方，避免冲突。
$before-frontend-dev 和 $before-backend-dev - 注入专门知识
为什么存在： AI模型有“预训练知识” - 来自数百万代码库的一般模式。但您的项目有与通用模式不同的特定约定。
它实际上做什么：
- 读取
.trellis/spec/frontend/或.trellis/spec/backend/ - 将项目特定模式加载到AI的工作上下文中：
- 组件命名约定
- 状态管理模式
- 数据库查询模式
- 错误处理标准
为什么这重要：
- 没有before-*-dev：AI编写不匹配项目风格的通用代码。
- 有before-*-dev：AI编写看起来像代码库其余部分的代码。
$check-frontend 和 $check-backend - 对抗上下文漂移
为什么存在： AI上下文窗口容量有限。随着对话进行，在会话开始时注入的指南变得不那么有影响力。这导致“上下文漂移”。
它实际上做什么：
- 重新读取先前注入的指南
- 比较编写的代码与那些指南
- 运行类型检查器和linter
- 识别违规并建议修复
为什么这重要：
- 没有check-*：上下文漂移未被注意，代码质量下降。
- 有check-*：漂移在提交前被捕获和纠正。
$check-cross-layer - 多维度验证
为什么存在： 大多数错误不是来自缺乏技术技能 - 它们来自“没想到”：
- 在一个地方更改了常量，错过了其他5个地方
- 修改了数据库模式，忘记更新API层
- 创建了一个实用函数，但类似的已经存在
它实际上做什么：
- 识别您的更改涉及哪些维度
- 对于每个维度，运行有针对性的检查：
- 跨层数据流
- 代码重用分析
- 导入路径验证
- 一致性检查
$finish-work - 整体预提交审查
为什么存在：
$check-* 技能专注于单个层内的代码质量。但真正的更改通常有横切关注点。
它实际上做什么：
- 整体审查所有更改
- 检查跨层一致性
- 识别更广泛的影响
- 检查是否应该记录新模式
$record-session - 为未来持久化记忆
为什么存在：
AI在这个会话期间构建的所有上下文将在会话结束时丢失。下一个会话的$start需要这个信息。
它实际上做什么：
- 记录会话摘要到
workspace/{developer}/journal-N.md - 捕获做了什么，学到了什么，以及剩余什么
- 更新索引文件以便快速查找
真实世界工作流示例
示例1：错误修复会话
[1/8] $start - AI在接触代码前需要项目上下文 [2/8] python3 ./.trellis/scripts/task.py create “Fix bug” --slug fix-bug - 跟踪工作以备将来参考 [3/8] $before-frontend-dev - 注入项目特定前端知识 [4/8] 调查并修复错误 - 实际开发工作 [5/8] $check-frontend - 重新验证代码对指南 [6/8] $finish-work - 整体跨层审查 [7/8] 人类测试和提交 - 人类在代码进入仓库前验证 [8/8] $record-session - 持久化记忆以供未来会话
示例2：规划会话（无代码）
[1/4] $start - 即使对于非编码工作也需要上下文 [2/4] python3 ./.trellis/scripts/task.py create “Planning task” --slug planning-task - 规划是有价值的工作 [3/4] 审查文档，创建子任务列表 - 实际规划工作 [4/4] $record-session (with --summary) - 规划决策必须记录
示例3：代码审查修复
[1/6] $start - 从先前会话恢复上下文 [2/6] $before-backend-dev - 在修复前重新注入指南 [3/6] 修复每个CR问题 - 在上下文中有指南的情况下处理反馈 [4/6] $check-backend - 验证修复没有引入新问题 [5/6] $finish-work - 记录CR的教训 [6/6] 人类提交，然后 $record-session - 保留CR教训
示例4：大型重构
[1/5] $start - 在进行重大更改前清晰基线 [2/5] 规划阶段 - 分解为可验证的块 [3/5] 分阶段执行，每个后使用 $check-* - 增量验证 [4/5] $finish-work - 检查是否应该记录新模式 [5/5] 记录多个提交哈希 - 将所有提交链接到一个功能
示例5：调试会话
[1/6] $start - 查看先前是否调查过此错误 [2/6] $before-backend-dev - 指南可能记录已知的陷阱 [3/6] 调查 - 实际调试工作 [4/6] $check-backend - 验证调试更改不会破坏其他东西 [5/6] $finish-work - 调试发现可能需要记录 [6/6] 人类提交，然后 $record-session - 调试知识是有价值的
要强调的关键规则
- AI从不提交 - 人类测试和批准。AI准备，人类验证。
- 代码前指南 -
$before-*-dev技能注入项目知识。 - 代码后检查 -
$check-*技能捕获上下文漂移。 - 记录一切 - $record-session 持久化记忆。
第三部分：自定义您的开发指南
解释第一部分和第二部分后，检查项目的开发指南是否需要自定义。
步骤1：检查当前指南状态
检查.trellis/spec/是否包含空模板或自定义指南：
# 检查文件是否仍然是空模板（查找占位符文本）
grep -l "To be filled by the team" .trellis/spec/backend/*.md 2>/dev/null | wc -l
grep -l "To be filled by the team" .trellis/spec/frontend/*.md 2>/dev/null | wc -l
步骤2：确定情况
情况A：首次设置（空模板）
如果指南是空模板（包含“To be filled by the team”），这是首次在此项目中使用Trellis。
向开发者解释：
“我看到.trellis/spec/中的开发指南仍然是空模板。这对于新的Trellis设置是正常的！
模板包含占位符文本，需要用您的项目的实际约定替换。没有这个，$before-*-dev 技能不会提供有用的指导。
您的第一个任务应该是填写这些指南：
- 查看您现有的代码库
- 识别已经在使用的模式和约定
- 在指南文件中记录它们
例如，对于.trellis/spec/backend/database-guidelines.md：
- 您的项目使用什么ORM/查询库？
- 迁移如何管理？
- 表/列的命名约定是什么？
您希望我帮助您分析代码库并填写这些指南吗？”
情况B：指南已经自定义
如果指南有真实内容（没有“To be filled”占位符），这是一个现有设置。
向开发者解释：
“很好！您的团队已经自定义了开发指南。您可以立即开始使用$before-*-dev 技能。
我建议阅读.trellis/spec/以熟悉团队的编码标准。”
步骤3：帮助填写指南（如果为空）
如果开发者想要帮助填写指南，创建一个功能来跟踪这个：
python3 ./.trellis/scripts/task.py create "Fill spec guidelines" --slug fill-spec-guidelines
然后系统地分析代码库并填写每个指南文件：
- 分析代码库 - 查看现有代码模式
- 记录约定 - 写下您观察到的，不是理想
- 包含示例 - 引用项目中的实际文件
- 列出禁止模式 - 记录团队避免的反模式
逐个文件处理：
backend/directory-structure.mdbackend/database-guidelines.mdbackend/error-handling.mdbackend/quality-guidelines.mdbackend/logging-guidelines.mdfrontend/directory-structure.mdfrontend/component-guidelines.mdfrontend/hook-guidelines.mdfrontend/state-management.mdfrontend/quality-guidelines.mdfrontend/type-safety.md
完成入职会话
覆盖所有三个部分后，总结：
“您现在已入职到Trellis工作流系统！这是我们覆盖的内容：
- 第一部分：核心概念（为什么这个工作流存在）
- 第二部分：真实世界示例（如何应用工作流）
- 第三部分：指南状态（空模板需要填写 / 已经自定义）
下一步（告诉用户）：
- 运行
$record-session记录这次入职会话 - [如果指南为空] 开始填写
.trellis/spec/指南 - [如果指南就绪] 开始您的第一个开发任务
您想先做什么？”