gjalla-spec

目標

最も優れ、洗練され、効果的なソフトウェアシステムは、十分な情報に基づき、綿密に計画され、検証可能なものです。
最終成果物は、問題や動機、技術的アプローチ、変更点（実装後にシステムのどの特性が変わるか）、検証基準を網羅した、参照資料として機能する計画書／仕様書です。
最初のステップは、常に現状を理解することです。gjalla（CLI または MCP）を使用して、アーキテクチャ、機能、データフローなど、この問題や解決策の領域に関連するマスタースペックの部分を取得します。また、最終的な解決策にどのような制約があるのかを把握するため、gjalla のルールも取得します。
関連する特性と制約を理解したら、ソースコードから確認する必要のある具体的な詳細を特定して収集します。
これで、自分で調べられる情報はすべて揃いました。提案する解決策の詳細に影響する未解決の疑問はありますか？ある場合は、ユーザーに確認してください。

必要な情報がすべて揃ったら、gjalla spec new を実行して、編集する変更仕様書のひな形を生成します。仕様書の成果物が正式な基準となるワークフローではこれが必須であり、実装完了後に gjalla プラットフォームがマスタースペックへの変更の検証とマージを支援します。
最終目標、コンテキスト（アーキテクチャ、データフロー、ユースケースなど）、ルールや制約を十分に検討し、目標に対する洗練された、保守しやすく、効果的な解決策を設計します。

本番環境向けの仕様書／参照資料に必要な情報は次のとおりです。

• 問題の説明：どのようなユーザーまたはシステムの問題を解決しますか？
• 目標：完了時に、何が満たされていなければなりませんか？
• 対象外：明示的に対象外とするものは何ですか？
• 動作要件：この機能が示すべき観察可能な動作、つまりシステム内に新たに備わる機能の特性です。システムが何かを許可または禁止する要件については、ユーザーにどう見えるかではなく、システムの状態として記述し、それを適用するファイルと関数を明記してください。コード上の担当箇所がない要件は、単なる願望です。
• 脅威モデルとセキュリティ要件：この設計で、どのような敵対的なセキュリティ事例を考慮しましたか？安全なソフトウェアシステムに必要な特性のうち、解決策に組み込み、後退が起きないことを確認するテストを用意すべきものは何ですか？
• 技術的アプローチ：どのように構築しますか？アーキテクチャ、データフロー、機能の範囲、その他の gjalla のプリミティブにどのような影響がありますか？
• 検証戦略：正常系、異常系、エッジケースを対象にしたユニットテストと統合テストは当然必要です。さらに、セキュリティと安全性（AI OWASP Top 10 など、一般的な安全なコーディング上の落とし穴や、脆弱性につながるほかのセキュリティ上のミスをテストに含めているか）、保守性、パフォーマンス、ユーザーエクスペリエンス、またはコンプライアンス、ビジネス上の制約、プラットフォーム上の制約など、ドメイン固有の検証基準も検討してください。現状では失敗し、これを構築すると合格するテストを少なくとも1つ明記してください。それを挙げられない場合、目標がまだ実装に向けて具体化されていません。
• 依存関係：事前に存在またはデプロイされている必要があるものは何ですか？プロジェクトがシステムの一部であり、相互運用性に影響する可能性がある場合は、gjalla を参照してください。
• ロールバック計画：問題が発生した場合、安全に元に戻すにはどうしますか？

ガイドライン

• 仕様書や計画書は小説ではありません。背景情報やコンテキストを含めることは問題ありません（むしろ望ましいです）が、明確で、重要性があり、関連性が高く、冗長すぎないようにしてください。
• 目標は、意図しない結果を未然に防ぐことです。二次的な影響も考慮して、起こり得る想定外の事態を先回りして検討してください。

提示して承認を得る

仕様にまとめた解決策に納得できたら、人間に提示して承認を得てください。これは gjalla-autonomous プロセスにおける 2 回の人間による承認ゲートの 1 つ目（もう 1 つはコミット時）です。利用できる場合は、ネイティブの計画提示機能（Claude の計画モード、Cursor の計画機能）を使ってください。そうでない場合は、仕様をそのまま提示して返答を待ってください。明示的な承認を得るまで、実装を始めないでください。

承認されたら、実装を開始してください。Claude Code を使っている場合は、承認が gjalla によって自動的に記録されるため、ほかに記録する必要はありません。