trellis-check

コード品質チェック

最近作成したコードの包括的な品質検証です。仕様への準拠、レイヤー間の安全性、コミット前のチェックを組み合わせます。

---

ステップ 1：変更内容を特定する

git diff --name-only HEAD
git status

ステップ 2：タスクの成果物と適用される仕様を読む

現在のタスクの成果物を次の順に読みます。

• prd.md
• design.md（存在する場合）
• implement.md（存在する場合）

python3 ./.trellis/scripts/get_context.py --mode packages

変更した各パッケージ／レイヤーについて、仕様インデックスを読み、「品質チェック」セクションの指示に従います。

cat .trellis/spec/<package>/<layer>/index.md

参照されている具体的なガイドラインファイルを読みます。インデックスは参照先を示すものであり、目的そのものではありません。

ステップ 3：プロジェクトのチェックを実行する

プロジェクトの lint、型チェック、テストコマンドを実行します。次に進む前に、失敗した項目を修正します。

ステップ 4：チェックリストに照らして確認する

コード品質

• Linter は成功していますか？
• 型チェッカーは成功していますか（該当する場合）？
• テストは成功していますか？
• デバッグ用ログが残っていませんか？
• 警告の抑制や型安全性を回避する記述はありませんか？

テストカバレッジ

• 新しい関数にユニットテストを追加しましたか？
• バグ修正に回帰テストを追加しましたか？
• 動作を変更した場合、既存のテストを更新しましたか？

仕様との同期

• .trellis/spec/ を更新する必要がありますか？（新しいパターン、規約、得られた知見など）

「バグを修正したり、すぐには分からないことに気付いたりした場合、将来の自分が同じ問題に遭遇しないよう、記録しておくべきでしょうか？」→ はいの場合、該当する仕様ドキュメントを更新します。

スコープの順守

• タスクで必要とされていないコードの整理をしていませんか？
• まだ存在しないケースのために、抽象化、設定、拡張ポイントを追加していませんか？
• 発生し得ない状態に対して、推測に基づくフォールバックを追加していませんか？
• 受け入れ条件に記載されていないファイルを変更していませんか？
• 動作が実際に定義されている箇所を修正せず、呼び出し側に回避策を追加していませんか？

ステップ 5：レイヤー間の観点（該当する場合）

変更が単一レイヤー内に収まる場合は、このステップを省略します。

A. データフロー（変更が 3 つ以上のレイヤーに及ぶ場合）

• 読み取りフローを正しく追跡できますか：Storage → Service → API → UI
• 書き込みフローを正しく追跡できますか：UI → API → Service → Storage
• 型／スキーマはレイヤー間で正しく受け渡されていますか？
• エラーは呼び出し側に適切に伝播していますか？

B. コードの再利用（定数の変更、ユーティリティの作成）

• 新しく作成する前に、既存の類似コードを検索しましたか？

  grep -r "pattern" src/
  

• 同じ値が繰り返されている場合、それは呼び出し側が一緒に変更する必要のある、安定した単一の概念を表していますか？その場合に限り抽出します。現時点でたまたま一致しているだけの 2 つのリテラルは、分けたままにしてください。
• 一括変更後、すべての出現箇所を更新しましたか？

C. インポート／依存関係（新しいファイルを作成する場合）

• インポートパス（相対パスと絶対パス）は正しいですか？
• 循環依存はありませんか？

D. 同一レイヤー内の一貫性

• 同じ概念を使っているほかの箇所でも、一貫性が保たれていますか？

---

ステップ 6：報告と修正

見つけた違反をすべて報告します。その後、次のように対応します。

• 機械的かつ局所的な問題（lint の軽微な問題、型の不足、誤ったインポート、到達不能な分岐、アサーションの失敗）→ その場で修正し、プロジェクトのチェックを再実行します。
• 設計や判断に関わる問題（共有概念の命名、モジュール境界の移動、公開インターフェースの変更、動作をどこに持たせるかの再割り当て）→ 根拠と推奨事項を記録し、そこで停止します。黙って書き換えないでください。

修正によって現在のタスクのスコープ外にあるファイルに触れることになる場合は、その旨を伝えて停止します。変更範囲を広げないでください。