設計 (canon)
設計とは、後続のセッションが誰にも尋ねずに なぜ（決定事項、canon/decisions/D-n.md）と 何が成立すべきか（ルール、canon/rules/<domain>/BR-n.md）を読めるようにすることです。この会話の中だけでしか存在しない設計は失われます。
1. モードを選択する
| モード | 読むもの | 焦点 |
|---|---|---|
architecture | references/mode-architecture.md、references/architecture-patterns.md | レイヤー、境界、C4、移行 |
api | references/mode-api.md、references/api-design.md | エンドポイント/コマンド、エラー、認証、ページネーション |
database | references/mode-database.md、references/database-design.md | スキーマ、インデックス、マイグレーション、アクセスパターン |
system | references/mode-system.md、references/system-design.md | SLA、障害モード、キャパシティ |
module | references/mode-module.md | 責任、深さ（削除テスト）、シーム、依存関係カテゴリ |
必要なモードのファイルのみを読んでください。設計がそれらに触れる場合は、横断的リファレンス（references/cross-cutting/：認可、エラーハンドリング、冪等性、セッション識別）も参照してください。
2. 設計の前に
canon context <path|domain|C-n>：現在のドメイン全体、そのルール、受け入れられた決定、および未完了の変更を確認します。設計はアクティブなルールや受け入れられた決定と矛盾してはなりません。矛盾する必要がある場合は、その旨を述べ、同じ変更の中でそれらを変更してください。canon search <topic>：同じ質問に関する以前の決定やメモを検索します。拡張するか、上書きします（--supersedes D-nを使用）。黙ってやり直してはいけません。- 独自に発明する前に、1〜3つの成熟した製品やライブラリが同じ問題をどのように解決しているかを調べてください。
- 構造を提案する前に、変更する既存のコード（シンボル、呼び出し元）を読んでください。
3. 設計
- 選択肢を列挙する前に問題を枠組みしてください：この設計はどのような質問に答えるべきか、どのようなシナリオに役立つべきか？既存の設計を評価する場合、欠陥のリストは入力であって枠組みではありません。欠陥リストからのみ構築された計画はパッチであり、設計ではありません。
- 少なくとも2つの現実的な選択肢を、そのトレードオフと推奨とともに提示してください。現実的とは、異なる設計を意味し、「3つの修正」対「10の修正」のように1つの設計を多かれ少なかれやることは（同じ1つの）選択肢です。3つ以上の選択肢または複数の次元がある場合は、記憶による賛否両論リストではなく、次元ごとに推論を記述してください。
- 推奨を提示する前に、問題と選択肢は見えるがあなたの推奨は見えないサブエージェントに一度だけチャレンジさせてください。質問自体の枠組みが間違っていないか、真に異なる設計が欠けていないか、各選択肢はどのシナリオで失敗するかを尋ねてください。提起された点に対処した上で推奨してください。インターフェースを変更しない1つのモジュール内の小さな設計に限り、これをスキップできます。その場合はスキップしたことと理由を述べてください。
- ライブラリ、バージョン、APIを提案する前に、現在の公式ドキュメントを確認してください。
- 投機的なプロトタイプで議論するよりも速く答えが出る質問（このステートマシンやデータモデルは使用に耐えるか、いくつかの画面レイアウトのうちどれが機能するか）は、まず canon-prototype スキルで解決します。その後、設計はプロトタイプが示したことを引用します。
- 曖昧な目標はまず定量化してください（「高速」→ Y rps で p99 X ms 未満）。
- 設計が対応するすべてのシナリオは、処理すべきビジネスレベルの障害（制限超過、支払い拒否、途中での権限失効、上流の障害）を少なくとも1つ挙げ、それらがどのように大きくかつ回復可能に失敗するかを示してください。「該当する障害モードはない」という主張は、仮定するのではなく、論証しなければなりません。
- 各選択肢の複雑さを、そのシナリオが発生したときのコストと比較検討し、各シナリオに1つの質問をしてください：通常の運用はそれに至るか？canon の場合、複数のセッションが同時に機能して完了することは通常の使用です。テストがどのように再現できるかは判断基準になりません。異常なセットアップやアクションを必要とする状況（システムコマンドをラップするユーザーのラッパー、誰も使わない非デフォルトのバックエンド、特定のプロセスを途中で強制終了すること、セキュリティ境界を越えない悪意のある入力）は、既知の制限（決定の
后果またはルール内の1行）となり、新しいメカニズムにはなりません。データ損失、セキュリティ、プロジェクトの約束（canon の場合、canon/product.md の P1 から P7）の違反は例外です。 - ドラフトを自分でモードのレンズと照らし合わせてレビューしてください。並列レビューサブエージェント（レンズごとに1つ、モードファイルを参照）はオプションです。各エージェントはゼロコンテキストから始まり、数万トークンを消費するため、影響範囲が大きい場合（モジュール間、公開API、データ移行、セキュリティ）にのみ使用してください。
品質ゲート（すべて合格するか、どれが合格しないかとその理由を述べること）
| モード | ゲート |
|---|---|
architecture | すべての非機能要件に測定可能なアーキテクチャ上の回答がある；すべての緊張に根拠のある決定がある；高リスクに緩和策がある；ロールバックを伴う移行フェーズがある |
api | すべての操作にそのエラーがある；すべての操作にその認証要件がある；セキュリティ問題は解決されるか、根拠をもって受け入れられる；ページネーションとレート制限が明記されている |
database | すべての外部キーにインデックスが張られている；すべてのテーブルがアクセスパターンによって正当化されている；すべてのスキーマ変更に無停止マイグレーションがある；金額に浮動小数点型を使用していない、タイムスタンプにタイムゾーンが設定されている |
system | SLAターゲット（スループット、p99、可用性）がある；無緩和の単一障害点がない；すべてのコンポーネントに障害モードと劣化がある；1倍/10倍/100倍のキャパシティが検討されている |
module | 依存関係の循環がない；モジュールごとに1つの明確な責任がある；すべてのモジュールが削除テストに合格する；単一のアダプタしかないシームがない；ブラックボックスとしてテストするのに十分な公開インターフェースがある；依存関係は注入可能である |
横断的考慮事項（毎回評価すること；理由を述べてのみスキップ可）
| 関心事 | いつ | 行うこと |
|---|---|---|
| セキュリティ | ユーザー入力、認証、ストレージ、外部呼び出し | データフローをトレースし、脅威と緩和策を列挙する |
| 並行性 | 共有状態、複数のセッションまたはプロセス | 通常の使用でそれを壊す可能性のあるインターリーブと、それをアトミックにするものを挙げる；稀なものは、データ損失がなければ既知の制限とする |
| パフォーマンス | レイテンシに敏感なパス、大量データ | 予算を設定し、設計がそれを満たすことを示す |
| 可観測性 | 新しいコンポーネント | 何がログまたは記録され、障害がどのように認識されるか |
| データプライバシー | PIIまたはその他のユーザーデータ | その機密性を分類する；保存時と転送時の暗号化；保持期間と削除；誰が読むかまたは変更するかの監査証跡 |
4. 設計を記録する
- 決定 各現実的な選択に対して：
canon decision new --title "..."→背景（事実、データ）、方案（すべての選択肢に採用または否决と理由を記載、それぞれ少なくとも1つ）、决定、后果を記入します。中国語で記述します（canon/ の文書は中国語です）。選択肢の下で、事実の出典を1行で引用します：- 来源：<URL または リポジトリパス> "<正確な引用、8文字以上>"— まず外部の実践を調査し、それを引用します；新しい決定には少なくとも1つの出典が必要であり、ランディング時にそれぞれの新しい出典を取得し、引用が実際に存在しない場合は却下します。自己評価スコアや信頼度を追加しないでください：誰も確認できません。 - ルール 設計が製品に課すすべての振る舞いに対して：
canon rule new --domain <d> --title "..."。1つのルール = 1つのトリガーと1つの結果；规则と例子に、境界の両側の具体的な入力を記入します。この変更が実装しない（そのコードは計画の後のステップで作成される）振る舞いは、ルールのフロントマターにstatus: plannedを設定します：规则と例子は必要ですが、テストは不要です。それを実装する変更はrules:の下にリストし、アクティブにします。計画されたルールの例子では、設計が確定する境界のみを固定します；実装が見つけるエッジケースは、それを構築するステップによって追加されます。 - 変更ファイル（
canon/changes/C-n.md）：为什么/要改什么、決定とルールを参照します。 - 設計がコンテナ（ランタイムパーツ、データの保存場所）またはメインフローを変更する場合は、同じ変更の中で
canon/architecture.mdを更新します：これは現在のシステムを説明し、各部分の末尾にその決定番号を付けます。その決定番号を、あなたが決定したものと照合します：上書きまたは修正されたものは、書き換える行を意味します。 - 通常通りランディングします（
canon work land）。ルールレビューは、決定とルールをドメイン全体と概要に対して読み、ブロックされたものを修正します。
設計ごとの個別の文書は不要です：実装前に固定する価値のあるインターフェース（型、コマンドシグネチャ、スキーマ）は、変更ファイルまたはコード自体に含めます。