gjalla-spec-review

包括的な仕様レビュー

最善で、最も洗練され、効果的なソフトウェアシステムとは、十分な情報に基づき、綿密に計画され、検証可能なものです。 最終的な成果物は、問題と動機、技術的なアプローチ、変更点（実装後にシステムのどのような特性が変わるか）、検証基準を網羅した、参照ドキュメントとして機能する計画／仕様です。

あなたのタスクは、この仕様が期待に応え、エンジニアの手に渡った後に堅実な実装につながるよう、複数の専門家の視点からレビューすることです。

基準：設計は洗練され、よく練られ、最小限で、保守しやすく、過剰な設計がなく、チームが自信を持ってリリースできるものであるべきです。ただ動くだけで、この基準を満たさない仕様は完成とは言えません。

有効性レビュー

最初に実施してください。他のすべての観点では、構築するものが適切に定義されているかを確認しますが、明示された問題と同じものに取り組んでいるかを確認するのは、このレビューだけです。

• 目標を言い換え、次に仕組みを言い換えてください。それらは同じギャップを埋めていますか？
• 何かを防ぐことが目標に含まれる場合、望ましくない結果に至る最も手軽な方法は何ですか？敵対的なユーザーや無関心なユーザーがたどる経路を追ってください。その経路が変更対象のコードを通らないなら、どれほど優れた変更であっても、目標を達成できない可能性があります。
• どのレイヤーがそれを強制しますか？クライアント側の制御は、あくまで提案にすぎません。
• 仕様は問題を解決していますか。それとも、誰かが最初に提案した解決策を実現しているだけですか？

アーキテクチャレビュー（必要に応じて gjalla マスタースペックを参照）

• 設計は既存のシステムに適合し、レイヤーの境界を尊重していますか？
• 新しいコンポーネントは、適切なレイヤーと所有権の階層に配置されていますか？
• より広範なシステム（リポジトリをまたぐ統合、将来の目標など）との互換性はありますか？
• 過剰な設計になっていたり、理解や保守が難しくなる複雑さを持ち込んだりしていませんか？これは主観的な判断ではなく、具体的な基準で確認してください。ほかの変更がリリースされるまで、実質的にデッドコードとなる部分はありませんか？ある場合は今削除し、フォローアップ事項として記録してください。誰も変更を求めていない設定項目や、過度に複雑な抽象化も同様です。目標は、効果的で、洗練され、よく練られ、時間とともにコードベースをより整理され直感的なものにする解決策です。
• 新しいコマンド、エンドポイント、ファイル、概念は、既存のものとトリガー、データソース、出力先を共有していますか？確立されたパターンに従い、既存のコードやツールを再利用していますか？

セキュリティレビューと脅威モデル

脅威モデリングは仕様の一部であり、後から設ける審査工程ではありません。以下の質問は、意図的に差分だけに限定していません。危険な脆弱性はたいてい、この変更では触れないコードを経由して到達可能だからです。

• ここでの攻撃者は誰で、何を狙っていますか？少なくとも、最も手軽な方法を選ぶ無関心なユーザー、敵対的なユーザー、侵害された、または好奇心のあるチームメイト、別のテナントを考慮してください。
• それぞれについて、望ましくない結果に至る最短経路をたどってください。それを阻止するものは何で、その制御はどこにありますか？
• 以前は到達できなかった何が、今回の変更で到達可能になりますか？新しい利用者に新しいデータが公開されますか、新たな信頼境界を越えますか、インターネットに新たに公開される領域はありますか？
• すべての新しいエンドポイントで認証と認可を行い、ユーザー間やテナント間でデータが漏洩しないようにするなど、変更はデータセキュリティとプライバシーの境界を尊重していますか？
• データモデルは機微なデータ（個人識別情報、シークレット）を適切に扱っていますか？
• 入力は攻撃対象領域の境界で検証されていますか？
• 不正利用された場合、どうすればそれを把握できますか？何が、どこに記録されますか？

品質レビュー

• テスト戦略は、動作要件を満たすのに十分ですか？
• AI 生成コードでは通常、テストカバレッジ 100％が目標です。正常系、異常系、境界条件、セキュアコーディングのケースを網羅していますか？最終目標を踏まえ、適切かつ有効な統合テストの範囲が定められていますか？
• 受け入れ基準は、テスト可能なアサーションに対応していますか？

ユーザー体験の観点からのレビュー

• この機能は、提示された問題を解決しますか？
• ユーザーの視点から見て、障害が発生した場合に適切に対処できますか？
• この機能を見つけやすく、ドキュメントで説明していますか？

ガバナンスの観点からのレビュー

• 仕様は、現在有効なプロジェクトのルールと規約すべてに準拠していますか？（gjalla に保存されています。必要に応じて確認してください）
• ルールの例外や承認が必要ですか？
• この変更にはアーキテクチャ決定記録（ADR）が必要ですか？（ほとんどの場合は不要ですが、重大で新たなトレードオフをもたらすものは必要となる場合があります）

出力

各観点について、合格している点、リスクのある点、実装前に必要な具体的な変更を報告してください。ブロッカーと推奨事項を分けてください。