trellis-update-spec

Code-Spec を更新する - 実行可能な契約を記録する

デバッグ、実装、または議論を通じて価値のある知見を得たら、関連する code-spec ドキュメントを更新します。

タイミング：タスクの完了後、バグの修正後、または新しいパターンの発見後

---

Code-Spec 優先ルール（重要）

このプロジェクトで実装作業における「spec」とは、code-spec を意味します。

• 実行可能な契約（原則のみを記述した文章ではありません）
• 具体的なシグネチャ、ペイロードフィールド、環境変数キー、境界での動作
• テスト可能な検証／エラー動作

変更がインフラやレイヤー横断の契約に関わる場合、code-spec の詳細化は必須です。

必須となる条件

変更に以下のいずれかが含まれる場合、code-spec の詳細化を適用します。

• コマンドまたは API のシグネチャの新規追加／変更
• レイヤー横断のリクエスト／レスポンス契約の変更
• データベースのスキーマ／マイグレーションの変更
• インフラとの統合（ストレージ、キュー、キャッシュ、シークレット、環境変数の配線）

必須の出力（7 セクション）

該当するタスクでは、以下のすべてのセクションを含めます。

1. スコープ／トリガー
2. シグネチャ（コマンド／API／DB）
3. 契約（リクエスト／レスポンス／環境変数）
4. 検証とエラーのマトリクス
5. 正常／基本／異常のケース
6. 必須テスト（アサーション箇所を含む）
7. 誤りと正しい例（少なくとも 1 組）

---

Code-Spec を更新するタイミング

トリガー	例	対象の Spec
機能を実装した	新しい統合またはモジュールを追加した	関連する spec ファイル
設計上の決定をした	シンプルさより拡張性のパターンを選んだ	関連する spec と「設計上の決定」セクション
バグを修正した	エラー処理に潜在的な問題があると判明した	関連する spec（例：エラー処理のドキュメント）
パターンを発見した	コードを構成するより良い方法を発見した	関連する spec ファイル
落とし穴に遭遇した	Y の前に X を行う必要があると学んだ	関連する spec と「よくある間違い」セクション
規約を確立した	チームで命名パターンに合意した	品質ガイドライン
新たな思考のきっかけ	「Y を行う前に X を確認するのを忘れない」	guides/*.md（チェック項目として）

重要なポイント：Code-spec の更新は、問題に対処するときだけに行うものではありません。機能実装のたびに設計上の決定と契約が生まれ、将来の AI／開発者が安全に実装するために必要となります。

---

Spec 構成の概要

.trellis/spec/
├── <layer>/           # Per-layer coding standards (e.g., backend/, frontend/, api/)
│   ├── index.md       # Overview and links
│   └── *.md           # Topic-specific guidelines
└── guides/            # Thinking checklists (NOT coding specs!)
    ├── index.md       # Guide index
    └── *.md           # Topic-specific guides

重要：Code-Spec と Guide の違いを把握する

種類	場所	目的	内容のスタイル
Code-Spec	<layer>/*.md	AI に「安全に実装する方法」を伝える	シグネチャ、契約、マトリクス、ケース、テスト箇所
Guide	guides/*.md	AI が「何を考慮すべきか」を支援する	チェックリスト、質問、spec への案内

判断基準：自分に問いかけてください。

• 「これはコードの書き方だ」→ spec のレイヤーディレクトリに記載する
• 「これはコードを書く前に考慮すべきことだ」→ guides/ に記載する

例：

学び	誤った場所	正しい場所
「このタスクでは API Y ではなく API X を使う」	❌ guides/（思考ガイドには具体的すぎます）	✅ 関連する spec ファイル（具体的な規約）
「Y を行うときは X を確認する」	❌ spec ファイル（spec としては抽象的すぎます）	✅ guides/（思考チェックリスト）

Guide は spec の詳細なルールを重複させず、spec を参照する簡潔なチェックリストにします。

---

更新プロセス

ステップ 1：学んだことを特定する

以下の質問に答えます。

1. 何を学びましたか？（具体的に）
2. なぜ重要ですか？（どんな問題を防ぎますか？）
3. どこに記載すべきですか？（どの spec ファイルですか？）

ステップ 2: 更新タイプの分類

タイプ	説明	アクション
設計上の決定	なぜアプローチ Y ではなく X を選んだのか	「設計上の決定」セクションに追加
プロジェクトの規約	このプロジェクトで X をどのように行うか	該当するセクションに例を付けて追加
新しいパターン	発見された再利用可能なアプローチ	「パターン」セクションに追加
禁止パターン	問題を引き起こすもの	「アンチパターン」または「やってはいけないこと」セクションに追加
よくある間違い	犯しやすいミス	「よくある間違い」セクションに追加
規約	合意された標準	該当するセクションに追加
落とし穴	直感的に分かりにくい挙動	警告のコールアウトを追加

ステップ 3: 対象のコードスペックを読む

編集する前に、現在のコードスペックを読んで以下を確認します:

• 既存の構造を理解する
• コンテンツの重複を避ける
• 更新内容に適したセクションを見つける

cat .trellis/spec/<category>/<file>.md

ステップ 4: 更新を行う

以下の原則に従ってください:

1. 具体的にする: 抽象的なルールだけでなく、具体的な例を含める
2. なぜを説明する: これが防ぐ問題を明記する
3. コントラクトを示す: シグネチャ、ペイロードのフィールド、エラー時の挙動を追加する
4. コードを示す: 主要なパターンのコードスニペットを追加する
5. 短く保つ: セクションごとに 1 つの概念

ステップ 5: インデックスを更新する (必要に応じて)

新しいセクションを追加した場合、またはコードスペックのステータスが変わった場合は、カテゴリの index.md を更新してください。

---

更新テンプレート

インフラ/レイヤー横断作業の必須テンプレート

## Scenario: <name>

### 1. Scope / Trigger
- Trigger: <why this requires code-spec depth>

### 2. Signatures
- Backend command/API/DB signature(s)

### 3. Contracts
- Request fields (name, type, constraints)
- Response fields (name, type, constraints)
- Environment keys (required/optional)

### 4. Validation & Error Matrix
- <condition> -> <error>

### 5. Good/Base/Bad Cases
- Good: ...
- Base: ...
- Bad: ...

### 6. Tests Required
- Unit/Integration/E2E with assertion points

### 7. Wrong vs Correct
#### Wrong
...
#### Correct
...

設計上の決定を追加する

### 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...

プロジェクトの規約を追加する

### 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.

新しいパターンを追加する

### 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.

禁止パターンを追加する

### 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
\`\`\`

よくある間違いを追加する

### Common Mistake: Description

**Symptom**: What goes wrong

**Cause**: Why this happens

**Fix**: How to correct it

**Prevention**: How to avoid it in the future

落とし穴を追加する

> **Warning**: Brief description of the non-obvious behavior.
>
> Details about when this happens and how to handle it.

---

インタラクティブモード

何を更新すべきか分からない場合は、以下の問いに答えてください:

1. 今何を終えましたか?

   • バグを修正した
   • 機能を実装した
   • コードをリファクタリングした
   • アプローチについて議論した

2. 何を学び、または決定しましたか?

   • 設計上の決定 (なぜ Y ではなく X か)
   • プロジェクトの規約 (X をどのように行うか)
   • 直感的に分かりにくい挙動 (落とし穴)
   • より良いアプローチ (パターン)

3. 将来の AI/開発者がこれを知る必要がありますか?

   • コードがどのように動作するかを理解するために → はい、スペックを更新する
   • 機能を保守または拡張するために → はい、スペックを更新する
   • 同じ間違いを繰り返さないために → はい、スペックを更新する
   • 純粋に一度限りの実装上の詳細 → スキップしてもよい

4. どの領域に関係しますか?

   • バックエンドコード
   • フロントエンドコード
   • レイヤー横断のデータフロー
   • コードの構成/再利用
   • 品質/テスト

---

品質チェックリスト

コードスペックの更新を終える前に:

• 内容は具体的で実行可能ですか?
• コード例を含めましたか?
• WHAT だけでなく WHY を説明しましたか?
• 実行可能なシグネチャ/コントラクトを含めましたか?
• バリデーションとエラーマトリクスを含めましたか?
• Good/Base/Bad のケースを含めましたか?
• アサーションポイントを伴う必要なテストを含めましたか?
• 正しいコードスペックファイルにありますか?
• 既存のコンテンツと重複していませんか?
• 新しいチームメンバーが理解できる内容ですか?

---

他のコマンドとの関係

Development Flow:
  Learn something → `update-spec` (Trellis command) → Knowledge captured
       ↑                                  ↓
  `break-loop` (Trellis command) ←──────────────────── Future sessions benefit
  (deep bug analysis)

• ``break-loop (Trellis コマンド) - バグを深く分析し、しばしば必要なスペック更新を明らかにします
• ``update-spec (Trellis コマンド) - 実際に更新を行います
• ``finish-work (Trellis コマンド) - スペックの更新が必要かどうかを確認するよう促します

---

基本理念

コードスペックは生きたドキュメントです。あらゆるデバッグセッション、あらゆる「ひらめきの瞬間」は、実装コントラクトをより明確にする機会です。

目標は 組織の記憶 です:

• 一人が学んだことを、全員が活用できる
• AI が 1 回のセッションで学んだことを、将来のセッションへと引き継ぐ
• 間違いが文書化されたガードレールになる