Back to Details

update-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Update Code-Spec - Capture Executable Contracts

更新Code-Spec - 记录可执行契约

When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant code-spec documents.
Timing: After completing a task, fixing a bug, or discovering a new pattern
当你从调试、实现或讨论中学到有价值的内容时，使用本命令更新相关的code-spec文档。
时机：完成任务、修复bug或发现新模式之后

Code-Spec First Rule (CRITICAL)

Code-Spec首要原则（至关重要）

In this project, "spec" for implementation work means code-spec:
  • Executable contracts (not principle-only text)
  • Concrete signatures, payload fields, env keys, and boundary behavior
  • Testable validation/error behavior
If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
在本项目中，实现工作中的“spec”指的是code-spec：
  • 可执行契约（而非仅原则性文字）
  • 具体的签名、负载字段、环境变量键和边界行为
  • 可测试的验证/错误行为
如果变更涉及基础设施或跨层契约，必须遵循完整的code-spec规范。

Mandatory Triggers

触发强制规范的场景

Apply code-spec depth when the change includes any of:
  • New/changed command or API signature
  • Cross-layer request/response contract change
  • Database schema/migration change
  • Infra integration (storage, queue, cache, secrets, env wiring)
当变更包含以下任意内容时，必须遵循完整code-spec规范：
  • 新增/修改命令或API签名
  • 跨层请求/响应契约变更
  • 数据库模式/迁移变更
  • 基础设施集成（存储、队列、缓存、密钥、环境配置）

Mandatory Output (7 Sections)

必填输出（7个章节）

For triggered tasks, include all sections below:
  1. Scope / Trigger
  2. Signatures (command/API/DB)
  3. Contracts (request/response/env)
  4. Validation & Error Matrix
  5. Good/Base/Bad Cases
  6. Tests Required (with assertion points)
  7. Wrong vs Correct (at least one pair)
对于触发强制规范的任务，必须包含以下所有章节：
  1. 范围 / 触发原因
  2. 签名（命令/API/数据库）
  3. 契约（请求/响应/环境）
  4. 验证与错误矩阵
  5. 正常/基础/异常场景
  6. 所需测试（含断言点）
  7. 错误示例 vs 正确示例（至少一对）

When to Update Code-Specs

何时更新Code-Spec

TriggerExampleTarget Spec
Implemented a featureAdded template download with gigetRelevant 
backend/
or 
frontend/
file
Made a design decisionUsed type field + mapping table for extensibilityRelevant code-spec + "Design Decisions" section
Fixed a bugFound a subtle issue with error handling
backend/error-handling.md
Discovered a patternFound a better way to structure codeRelevant 
backend/
or 
frontend/
file
Hit a gotchaLearned that X must be done before YRelevant code-spec + "Common Mistakes" section
Established a conventionTeam agreed on naming pattern
quality-guidelines.md
New thinking trigger"Don't forget to check X before doing Y"
guides/*.md
(as a checklist item, not detailed rules)
Key Insight: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.
触发场景示例目标文档
完成功能实现使用giget新增模板下载功能相关的
backend/
或
frontend/
文件
确定设计决策使用类型字段+映射表实现扩展性相关code-spec + “设计决策”章节
修复bug发现错误处理中的潜在问题
backend/error-handling.md
发现新模式找到更优的代码结构方式相关的
backend/
或
frontend/
文件
遇到陷阱了解到必须先执行X再执行Y相关code-spec + “常见错误”章节
确立约定团队达成命名规范共识
quality-guidelines.md
触发新思考“执行Y前别忘了检查X”
guides/*.md
（作为 checklist 项，而非详细规则）
核心要点：Code-Spec更新不仅针对问题。每一次功能实现都包含设计决策和契约，这些内容对未来的AI/开发者安全执行任务至关重要。

Spec Structure Overview

文档结构概述

.trellis/spec/
├── backend/           # Backend coding standards
│   ├── index.md       # Overview and links
│   └── *.md           # Topic-specific guidelines
├── frontend/          # Frontend coding standards
│   ├── index.md       # Overview and links
│   └── *.md           # Topic-specific guidelines
└── guides/            # Thinking checklists (NOT coding specs!)
    ├── index.md       # Guide index
    └── *.md           # Topic-specific guides
.trellis/spec/
├── backend/           # 后端编码标准
│   ├── index.md       # 概述与链接
│   └── *.md           # 特定主题指南
├── frontend/          # 前端编码标准
│   ├── index.md       # 概述与链接
│   └── *.md           # 特定主题指南
└── guides/            # 思考清单（非编码规范！）
    ├── index.md       # 指南索引
    └── *.md           # 特定主题指南

CRITICAL: Code-Spec vs Guide - Know the Difference

至关重要：区分Code-Spec与Guide

TypeLocationPurposeContent Style
Code-Spec
backend/*.md
, 
frontend/*.md
Tell AI "how to implement safely"Signatures, contracts, matrices, cases, test points
Guide
guides/*.md
Help AI "what to think about"Checklists, questions, pointers to specs
Decision Rule: Ask yourself:
  • "This is how to write the code" → Put in 
    backend/
    or 
    frontend/
  • "This is what to consider before writing" → Put in 
    guides/
Example:
LearningWrong LocationCorrect Location
"Use 
reconfigure()
not 
TextIOWrapper
for Windows stdout"		❌ 
guides/cross-platform-thinking-guide.md
✅ 
backend/script-conventions.md
"Remember to check encoding when writing cross-platform code"❌ 
backend/script-conventions.md
✅ 
guides/cross-platform-thinking-guide.md
Guides should be short checklists that point to specs, not duplicate the detailed rules.
类型位置目的内容风格
Code-Spec
backend/*.md
, 
frontend/*.md
告诉AI“如何安全实现”签名、契约、矩阵、场景、测试点
Guide
guides/*.md
帮助AI“需要考虑什么”清单、问题、指向规范的链接
判断规则：问自己：
  • “这是代码的编写方式” → 放入
    backend/
    或
    frontend/
  • “这是编写代码前需要考虑的内容” → 放入
    guides/
示例:
知识点错误位置正确位置
“Windows平台stdout使用
reconfigure()
而非
TextIOWrapper
”		❌ 
guides/cross-platform-thinking-guide.md
✅ 
backend/script-conventions.md
“编写跨平台代码时记得检查编码”❌ 
backend/script-conventions.md
✅ 
guides/cross-platform-thinking-guide.md
指南应是指向规范的简短清单，而非重复详细规则。

Update Process

更新流程

Step 1: Identify What You Learned

步骤1：明确所学内容

Answer these questions:
  1. What did you learn? (Be specific)
  2. Why is it important? (What problem does it prevent?)
  3. Where does it belong? (Which spec file?)
回答以下问题：
  1. 你学到了什么？（请具体）
  2. 为什么重要？（能预防什么问题？）
  3. 属于哪个文档？（对应哪个spec文件？）

Step 2: Classify the Update Type

步骤2：分类更新类型

TypeDescriptionAction
Design DecisionWhy we chose approach X over YAdd to "Design Decisions" section
Project ConventionHow we do X in this projectAdd to relevant section with examples
New PatternA reusable approach discoveredAdd to "Patterns" section
Forbidden PatternSomething that causes problemsAdd to "Anti-patterns" or "Don't" section
Common MistakeEasy-to-make errorAdd to "Common Mistakes" section
ConventionAgreed-upon standardAdd to relevant section
GotchaNon-obvious behaviorAdd warning callout
类型描述操作
设计决策为何选择方案X而非Y添加到“设计决策”章节
项目约定本项目中X的实现方式添加到相关章节并附示例
新模式可复用的实现方法添加到“模式”章节
禁用模式会引发问题的实现方式添加到“反模式”或“禁止操作”章节
常见错误容易犯的错误添加到“常见错误”章节
约定规范达成共识的标准添加到相关章节
陷阱非直观的行为添加警告提示

Step 3: Read the Target Code-Spec

步骤3：阅读目标Code-Spec

Before editing, read the current code-spec to:
  • Understand existing structure
  • Avoid duplicating content
  • Find the right section for your update
bash
cat .trellis/spec/<category>/<file>.md
编辑前，先阅读当前的Code-Spec以：
  • 理解现有结构
  • 避免内容重复
  • 找到合适的更新位置
bash
cat .trellis/spec/<category>/<file>.md

Step 4: Make the Update

步骤4：执行更新

Follow these principles:
  1. Be Specific: Include concrete examples, not just abstract rules
  2. Explain Why: State the problem this prevents
  3. Show Contracts: Add signatures, payload fields, and error behavior
  4. Show Code: Add code snippets for key patterns
  5. Keep it Short: One concept per section
遵循以下原则：
  1. 具体明确：包含具体示例，而非抽象规则
  2. 解释原因：说明能预防的问题
  3. 展示契约：添加签名、负载字段和错误行为
  4. 展示代码：添加关键模式的代码片段
  5. 保持简洁：每个章节只讲一个概念

Step 5: Update the Index (if needed)

步骤5：更新索引（如需要）

If you added a new section or the code-spec status changed, update the category's 
index.md
.
如果添加了新章节或Code-Spec状态变更，更新对应分类的
index.md
。

Update Templates

更新模板

Mandatory Template for Infra/Cross-Layer Work

基础设施/跨层工作的必填模板

markdown
undefined
markdown
undefined

Scenario: <name>

场景: <名称>

1. Scope / Trigger

1. 范围 / 触发原因

  • Trigger: <why this requires code-spec depth>
  • 触发原因: <为何需要完整的code-spec规范>

2. Signatures

2. 签名

  • Backend command/API/DB signature(s)
  • 后端命令/API/数据库签名

3. Contracts

3. 契约

  • Request fields (name, type, constraints)
  • Response fields (name, type, constraints)
  • Environment keys (required/optional)
  • 请求字段（名称、类型、约束）
  • 响应字段（名称、类型、约束）
  • 环境变量键（必填/可选）

4. Validation & Error Matrix

4. 验证与错误矩阵

  • <condition> -> <error>
  • <条件> -> <错误>

5. Good/Base/Bad Cases

5. 正常/基础/异常场景

  • Good: ...
  • Base: ...
  • Bad: ...
  • 正常: ...
  • 基础: ...
  • 异常: ...

6. Tests Required

6. 所需测试

  • Unit/Integration/E2E with assertion points
  • 单元/集成/E2E测试及断言点

7. Wrong vs Correct

7. 错误示例 vs 正确示例

Wrong

错误示例

...
...

Correct

正确示例

...
undefined
...
undefined

Adding a Design Decision

添加设计决策

markdown
undefined
markdown
undefined

Design Decision: [Decision Name]

设计决策: [决策名称]

Context: What problem were we solving?
Options Considered:
  1. Option A - brief description
  2. Option B - brief description
Decision: We chose Option X because...
Example: ```typescript // How it's implemented code example ```
Extensibility: How to extend this in the future...
undefined
背景: 我们要解决什么问题？
考虑的选项:
  1. 选项A - 简要描述
  2. 选项B - 简要描述
决策: 我们选择选项X，因为...
示例: ```typescript // 实现方式 代码示例 ```
扩展性: 未来如何扩展该实现...
undefined

Adding a Project Convention

添加项目约定

markdown
undefined
markdown
undefined

Convention: [Convention Name]

约定: [约定名称]

What: Brief description of the convention.
Why: Why we do it this way in this project.
Example: ```typescript // How to follow this convention code example ```
Related: Links to related conventions or specs.
undefined
内容: 约定的简要描述。
原因: 本项目为何采用该约定。
示例: ```typescript // 如何遵循该约定 代码示例 ```
相关链接: 指向相关约定或规范的链接。
undefined

Adding a New Pattern

添加新模式

markdown
undefined
markdown
undefined

Pattern Name

模式名称

Problem: What problem does this solve?
Solution: Brief description of the approach.
Example: ``` // Good code example
// Bad code example ```
Why: Explanation of why this works better.
undefined
问题: 该模式解决什么问题？
方案: 实现方式的简要描述。
示例: ``` // 正确示例 代码示例
// 错误示例 代码示例 ```
优势: 为何该方案更优。
undefined

Adding a Forbidden Pattern

添加禁用模式

markdown
undefined
markdown
undefined

Don't: Pattern Name

禁止: 模式名称

Problem: ``` // Don't do this bad code example ```
Why it's bad: Explanation of the issue.
Instead: ``` // Do this instead good code example ```
undefined
问题: ``` // 禁止这样做 错误代码示例 ```
危害: 该方式引发的问题说明。
替代方案: ``` // 推荐做法 正确代码示例 ```
undefined

Adding a Common Mistake

添加常见错误

markdown
undefined
markdown
undefined

Common Mistake: Description

常见错误: 描述

Symptom: What goes wrong
Cause: Why this happens
Fix: How to correct it
Prevention: How to avoid it in the future
undefined
症状: 会出现什么问题
原因: 错误产生的根源
修复方式: 如何修正
预防措施: 未来如何避免
undefined

Adding a Gotcha

添加陷阱

markdown
> **Warning**: Brief description of the non-obvious behavior.
>
> Details about when this happens and how to handle it.
markdown
> **警告**: 非直观行为的简要描述。
>
> 该行为的触发条件及处理方式说明。

Interactive Mode

交互模式

If you're unsure what to update, answer these prompts:
  1. What did you just finish?
    • Fixed a bug
    • Implemented a feature
    • Refactored code
    • Had a discussion about approach
  2. What did you learn or decide?
    • Design decision (why X over Y)
    • Project convention (how we do X)
    • Non-obvious behavior (gotcha)
    • Better approach (pattern)
  3. Would future AI/developers need to know this?
    • To understand how the code works → Yes, update spec
    • To maintain or extend the feature → Yes, update spec
    • To avoid repeating mistakes → Yes, update spec
    • Purely one-off implementation detail → Maybe skip
  4. Which area does it relate to?
    • Backend code
    • Frontend code
    • Cross-layer data flow
    • Code organization/reuse
    • Quality/testing
如果你不确定要更新什么，回答以下问题：
  1. 你刚完成了什么？
    • 修复bug
    • 实现功能
    • 重构代码
    • 讨论实现方案
  2. 你学到或确定了什么？
    • 设计决策（为何选X而非Y）
    • 项目约定（本项目X的实现方式）
    • 非直观行为（陷阱）
    • 更优实现方式（模式）
  3. 未来的AI/开发者是否需要知道这些内容？
    • 了解代码工作原理 → 是，更新规范
    • 维护或扩展功能 → 是，更新规范
    • 避免重复错误 → 是，更新规范
    • 纯一次性实现细节 → 可跳过
  4. 属于哪个领域？
    • 后端代码
    • 前端代码
    • 跨层数据流
    • 代码组织/复用
    • 质量/测试

Quality Checklist

质量检查清单

Before finishing your code-spec update:
  • Is the content specific and actionable?
  • Did you include a code example?
  • Did you explain WHY, not just WHAT?
  • Did you include executable signatures/contracts?
  • Did you include validation and error matrix?
  • Did you include Good/Base/Bad cases?
  • Did you include required tests with assertion points?
  • Is it in the right code-spec file?
  • Does it duplicate existing content?
  • Would a new team member understand it?
完成Code-Spec更新前，请检查：
  • 内容是否具体且可执行？
  • 是否包含代码示例？
  • 是否解释了原因，而非仅说明做法？
  • 是否包含可执行签名/契约？
  • 是否包含验证与错误矩阵？
  • 是否包含正常/基础/异常场景？
  • 是否包含带断言点的所需测试？
  • 是否放在正确的Code-Spec文件中？
  • 是否重复了现有内容？
  • 新团队成员能否理解？

Relationship to Other Commands

与其他命令的关系

Development Flow:
  Learn something → /trellis:update-spec → Knowledge captured
       ↑                                  ↓
  /trellis:break-loop ←──────────────────── Future sessions benefit
  (deep bug analysis)
  • /trellis:break-loop
    - Analyzes bugs deeply, often reveals spec updates needed
  • /trellis:update-spec
    - Actually makes the updates (this command)
  • /trellis:finish-work
    - Reminds you to check if specs need updates
开发流程:
  学到内容 → /trellis:update-spec → 知识被记录
       ↑                                  ↓
  /trellis:break-loop ←──────────────────── 后续会话受益
  （深度bug分析）
  • /trellis:break-loop
    - 深度分析bug，通常会发现需要更新的规范
  • /trellis:update-spec
    - 实际执行更新（本命令）
  • /trellis:finish-work
    - 提醒你检查是否需要更新规范

Core Philosophy

核心理念

Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.
The goal is institutional memory:
  • What one person learns, everyone benefits from
  • What AI learns in one session, persists to future sessions
  • Mistakes become documented guardrails
Code-Spec是活文档。每一次调试、每一个“顿悟时刻”都是让实现契约更清晰的机会。
目标是机构知识留存：
  • 一个人学到的内容，所有人都能受益
  • AI在一次会话中学到的内容，能延续到后续会话
  • 错误会成为文档化的防护栏