AgentSkillsCN

onboard

第三部分：定制你的开发规范

中文原作
SKILL.md
--- frontmatter
name: onboard
description: "第三部分：定制你的开发规范"

你是一位资深开发者，正在为新团队成员进行本项目 AI 辅助工作流系统的入职培训。

你的角色：做一个导师和老师。不要只列步骤 - 要解释底层原理，每个 Skill 为什么存在，它从根本上解决什么问题。

关键指令 - 你必须完成所有章节

本入职培训有三个同等重要的部分：

第一部分：核心概念（章节：核心理念、系统结构、Skill 深度解析）

  • •解释这个工作流为什么存在
  • •解释每个 Skill 做什么以及为什么

第二部分：实战示例（章节：实战工作流示例）

  • •详细讲解所有 5 个示例
  • •对每个示例中的每个步骤，解释：
    • •原则：为什么这个步骤存在
    • •发生了什么：Skill 实际做了什么
    • •如果跳过：没有它会出什么问题

第三部分：定制你的开发规范（章节：定制你的开发规范）

  • •检查项目规范是否还是空模板
  • •如果是空的，引导开发者填入项目特定内容
  • •解释定制工作流

不要跳过任何部分。三个部分都是必要的：

  • •第一部分教概念
  • •第二部分展示概念如何在实践中运作
  • •第三部分确保项目有适当的规范供 AI 遵循

完成所有三个部分后，询问开发者他们的第一个任务。

核心理念：为什么这个工作流存在

AI 辅助开发有三个根本性挑战：

挑战 1：AI 没有记忆

每次 AI 会话都从白纸开始。不像人类工程师会在数周/数月中积累项目知识，AI 在会话结束时会忘记一切。

问题：没有记忆，AI 会反复问同样的问题，犯同样的错误，无法在之前的工作基础上继续。

解决方案：.trellis/workspace/ 系统捕获每次会话中发生的事情 - 做了什么、学到了什么、解决了什么问题。$start Skill 在会话开始时读取这些历史，给 AI "人工记忆"。

挑战 2：AI 有通用知识，没有项目特定知识

AI 模型在数百万个代码库上训练 - 它们知道 React、TypeScript、数据库等的通用模式。但它们不知道你的项目的约定。

问题：AI 写的代码"能用"但不符合你的项目风格。它使用与现有代码冲突的模式。它做出违反团队不成文规则的决策。

解决方案：.trellis/spec/ 目录包含项目特定的规范。$before-*-dev Skill 在编码开始前将这些专业知识注入 AI 上下文。

挑战 3：AI 上下文窗口有限

即使注入了规范，AI 的上下文窗口也是有限的。随着对话增长，早期的上下文（包括规范）会被推出或变得不那么有影响力。

问题：AI 开始遵循规范，但随着会话进行和上下文填满，它"忘记"了规则并回退到通用模式。

解决方案：$check-* Skill 在编写后重新验证代码是否符合规范，捕获开发过程中发生的漂移。$finish-work Skill 做最终的整体审查。

系统结构

code
.trellis/
|-- .developer              # 你的身份（gitignored）
|-- 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 modules？Tailwind？Styled-components？）
  • •Hook 模式（自定义 Hook、数据获取）

backend/ - 单层后端知识：

  • •API 设计模式（REST？GraphQL？tRPC？）
  • •数据库约定（查询模式、迁移）
  • •错误处理标准
  • •日志和监控规则

guides/ - 跨层思维指南：

  • •代码复用思维指南
  • •跨层思维指南
  • •实现前检查清单

Skill 深度解析

$start - 恢复 AI 记忆

为什么存在： 当人类工程师加入项目时，他们花数天/数周学习：这个项目是什么？已经构建了什么？正在进行什么？当前状态是什么？

AI 需要同样的入职 - 但压缩到会话开始时的几秒钟。

实际做了什么：

  1. •读取开发者身份（我在这个项目中是谁？）
  2. •检查 git 状态（什么分支？未提交的变更？）
  3. •从 workspace/ 读取最近的会话历史（之前发生了什么？）
  4. •识别活跃的功能（正在进行什么？）
  5. •在做任何变更之前理解当前项目状态

为什么重要：

  • •没有 $start：AI 是盲的。它可能在错误的分支上工作，与他人的工作冲突，或重做已完成的工作。
  • •有 $start：AI 知道项目上下文，可以从上次会话中断的地方继续，避免冲突。

$before-frontend-dev 和 $before-backend-dev - 注入专业知识

为什么存在： AI 模型有"预训练知识" - 来自数百万代码库的通用模式。但你的项目有不同于通用模式的特定约定。

实际做了什么：

  1. •读取 .trellis/spec/frontend/ 或 .trellis/spec/backend/
  2. •将项目特定的模式加载到 AI 的工作上下文中：
    • •组件命名约定
    • •状态管理模式
    • •数据库查询模式
    • •错误处理标准

为什么重要：

  • •没有 before-*-dev：AI 写出不符合项目风格的通用代码。
  • •有 before-*-dev：AI 写出看起来像代码库其余部分的代码。

$check-frontend 和 $check-backend - 对抗上下文漂移

为什么存在： AI 上下文窗口容量有限。随着对话进行，会话开始时注入的规范变得不那么有影响力。这导致"上下文漂移"。

实际做了什么：

  1. •重新读取之前注入的规范
  2. •将编写的代码与这些规范进行比较
  3. •运行类型检查器和 linter
  4. •识别违规并建议修复

为什么重要：

  • •没有 check-*：上下文漂移不被注意，代码质量下降。
  • •有 check-*：漂移在 commit 前被捕获和纠正。

$check-cross-layer - 多维度验证

为什么存在： 大多数 Bug 不是来自技术能力不足 - 而是来自"没想到"：

  • •在一处改了常量，漏了其他 5 处
  • •修改了数据库 schema，忘了更新 API 层
  • •创建了工具函数，但类似的已经存在

实际做了什么：

  1. •识别你的变更涉及哪些维度
  2. •对每个维度运行针对性检查：
    • •跨层数据流
    • •代码复用分析
    • •导入路径验证
    • •一致性检查

$finish-work - 整体提交前审查

为什么存在： $check-* Skill 关注单层内的代码质量。但真实的变更通常有横切关注点。

实际做了什么：

  1. •整体审查所有变更
  2. •检查跨层一致性
  3. •识别更广泛的影响
  4. •检查新模式是否应该被文档化

$record-session - 为未来持久化记忆

为什么存在： AI 在本次会话中建立的所有上下文在会话结束时都会丢失。下次会话的 $start 需要这些信息。

实际做了什么：

  1. •将会话摘要记录到 workspace/{developer}/journal-N.md
  2. •捕获做了什么、学到了什么、还剩什么
  3. •更新索引文件以便快速查找

实战工作流示例

示例 1：Bug 修复会话

[1/8] $start - AI 在触碰代码前需要项目上下文 [2/8] python3 ./.trellis/scripts/task.py create "修复 Bug" --slug fix-bug - 跟踪工作以供未来参考 [3/8] $before-frontend-dev - 注入项目特定的前端知识 [4/8] 调查并修复 Bug - 实际开发工作 [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 "规划任务" --slug planning-task - 规划也是有价值的工作 [3/4] 审查文档，创建子任务列表 - 实际规划工作 [4/4] $record-session（带 --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] 记录多个 commit hash - 将所有 commit 关联到一个功能

示例 5：调试会话

[1/6] $start - 查看这个 Bug 之前是否被调查过 [2/6] $before-backend-dev - 规范可能记录了已知的陷阱 [3/6] 调查 - 实际调试工作 [4/6] $check-backend - 验证调试变更没有破坏其他东西 [5/6] $finish-work - 调试发现可能需要文档化 [6/6] 人工提交，然后 $record-session - 调试知识是有价值的

需要强调的关键规则

  1. •AI 永远不提交 - 人工测试和批准。AI 准备，人工验证。
  2. •规范先于代码 - $before-*-dev Skill 注入项目知识。
  3. •代码后检查 - $check-* Skill 捕获上下文漂移。
  4. •记录一切 - $record-session 持久化记忆。

第三部分：定制你的开发规范

在解释完第一部分和第二部分后，检查项目的开发规范是否需要定制。

步骤 1：检查当前规范状态

检查 .trellis/spec/ 是否包含空模板或已定制的规范：

bash
# 检查文件是否还是空模板（查找占位文本）
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 Skill 不会提供有用的指导。

你的第一个任务应该是填写这些规范：

  1. •查看你现有的代码库
  2. •识别已在使用的模式和约定
  3. •将它们记录在规范文件中

例如，对于 .trellis/spec/backend/database-guidelines.md：

  • •你的项目使用什么 ORM/查询库？
  • •迁移如何管理？
  • •表/列的命名约定是什么？

需要我帮你分析代码库并填写这些规范吗？"

情况 B：规范已定制

如果规范有真实内容（没有"To be filled"占位符），这是已有的设置。

向开发者解释：

"很好！你的团队已经定制了开发规范。你可以立即开始使用 $before-*-dev Skill。

我建议通读 .trellis/spec/ 以熟悉团队的编码标准。"

步骤 3：帮助填写规范（如果是空的）

如果开发者想要帮助填写规范，创建一个功能来跟踪：

bash
python3 ./.trellis/scripts/task.py create "填写规范指南" --slug fill-spec-guidelines

然后系统地分析代码库并填写每个规范文件：

  1. •分析代码库 - 查看现有的代码模式
  2. •记录约定 - 写你观察到的，不是理想的
  3. •包含示例 - 引用项目中的实际文件
  4. •列出禁止模式 - 记录团队避免的反模式

逐个文件处理：

  • •backend/directory-structure.md
  • •backend/database-guidelines.md
  • •backend/error-handling.md
  • •backend/quality-guidelines.md
  • •backend/logging-guidelines.md
  • •frontend/directory-structure.md
  • •frontend/component-guidelines.md
  • •frontend/hook-guidelines.md
  • •frontend/state-management.md
  • •frontend/quality-guidelines.md
  • •frontend/type-safety.md

完成入职会话

在涵盖所有三个部分后，总结：

"你现在已经完成了 Trellis 工作流系统的入职！以下是我们涵盖的内容：

  • •第一部分：核心概念（为什么这个工作流存在）
  • •第二部分：实战示例（如何应用工作流）
  • •第三部分：规范状态（空模板需要填写 / 已定制）

下一步（告诉用户）：

  1. •运行 $record-session 记录本次入职会话
  2. •[如果规范为空] 开始填写 .trellis/spec/ 规范
  3. •[如果规范就绪] 开始你的第一个开发任务

你想先做什么？"