Graft — エージェントスキル ## 目的 Graft は、オプションで署名された Webhook を /hook/… で受け取り、Go の text/template で JSON を変換し、宛先 URL に転送します。管理者 API は /api/v1/ にあり、API キー認証を使用します。エージェントは、コードベースを小さなチームがパブリックインターネット上で実行できるように安全に保ち、テストなしで動作をマージしないようにする必要があります。 ## このスキルが適用される場合 このリポジトリのすべてのタスクに使用します: 新機能、バグ修正、リファクタリング、依存関係のバージョンアップ、リリース準備など。 ## 効率 (コードベースの作業方法) 1. スコープ — タスクに必要なパッケージのみを変更します (internal/httpapi、internal/connectors、internal/storage、internal/router など)。ドライブバイのリファクタリングを避けます。 2. 調査 — 編集する前に、機能のハンドラーとストレージパスを読み、既存のパターンを反映します (コンストラクター、エラーメッセージ、JSON フィールド名など)。 3. 単一の検証パス — 編集後、go fmt ./...、go vet ./...、go test ./... をタスクバッチの最後に 1 回実行します (毎回実行しないようにします)。 4. CGO — github.com/mattn/go-sqlite3 には、実際の DB テストに CGO が必要です。ローカルで CGO_ENABLED=0 を実行すると、SQLite バックエンドのテストを スキップ します。 CI / プリリリースでは CGO=1 を使用する必要があります (ワークフロードキュメントを参照)。 5. 依存関係 — 必要な場合にのみサードパーティモジュールを追加し、標準ライブラリを優先します。 ## 品質基準 (交渉不可) 1. エラー — err != nil を確認し、必要に応じて %w でラップします。HTTP 応答にスタックトレースや内部詳細を返さないでください。 2. セキュリティ — .agents/security-guidelines.md に従います (管理者認証、署名検証、保存時の暗号化、レート制限、ボディ制限、タイムアウトなど)。 3. ハンドラー — HTTP を薄く保ちます: 入力を検証し、ストレージ、connectors、transformer などを呼び出し、ステータスと JSON を書きます。セキュリティチェックを複製するのではなく、小さなヘルパーを使用することを優先します。 4. ログ — Webhook 本文や暗号化されたシークレットをログにしないでください。 ## テスト契約 (パブリック / すべての機能の前に) .agents/FEATURE-TEST-MATRIX.md を参照して、機能 → パッケージ → テストファイルの正規マップを確認してください。ルール: - 新しい機能または動作の変更 には、リストされているパッケージ (テーブル駆動の場合は複数のケース) に ユニットテスト を含めるか更新する必要があります。 - 統合: internal/integration は管理者 + Webhook + 転送のエンドツーエンドをカバーします。リリースを検証するときは、CGO を使用して実行します。 - SQLite が環境で利用できない場合、テストをスキップすることは、開発者マシンのみで許可されます。 リリースパイプラインでは CGO を使用して実行する必要があります。 ## 必須完了チェックリスト 1. go fmt ./... 2. go vet ./... 3. go test ./... (ローカル; CGO はオプション) 4. パブリックリリース または CI マージ の前に: go test -race ./... を CGO_ENABLED=1 で実行し、C ツールチェーンを使用します (.agents/workflows/test-and-lint.md を参照)。 ## クロスリファレンス | ドキュメント | 役割 | |----------|------| | .agents/coding-standards.md | アーキテクチャ、DI、並行性 | | .agents/security-guidelines.md | セキュリティ要件 | | .agents/workflows/test-and-lint.md | 正確なコマンドと CI ノート | | .agents/FEATURE-TEST-MATRIX.md | 必要なテストごとにエリア |