| name | decree-adr-writer |
| description | Writes Architecture Decision Records (ADRs) for the DECREE project
(Dynamic Realtime Exploit Classification & Evaluation Engine).
Rebuilds Docker Compose services, verifies container health, then
documents the implementation in Japanese following the project's ADR template.
Triggers on phrases like 「ADRを書いて」「ADRにまとめて」「ADRに記録して」
「コンテナ再ビルドしてADR書いて」「実装まとめをADRに」「docs/ADR」,
or any request to document a completed DECREE implementation.
Also triggers when asked to write an ADR without container operations
(e.g. 「ADRだけ書いて」). Always use this skill for any ADR-related
task in the DECREE project, even if the user does not explicitly
mention "ADR" but asks to document or record an architectural decision.
|
DECREE ADR Writer
DECREEプロジェクトの実装完了後にコンテナ再ビルド・起動確認を行い、
ADRファイルに日本語で実装内容をまとめるスキル。
DECREE プロジェクト概要
脆弱性のリアルタイムモニタリングと攻撃面の Three.js/WebGPU 可視化を行うOSS。
MVPサービス構成:
| サービス | 言語 | 役割 |
|---|
| decree-scanner | Rust | SBOM生成・脆弱性照合・EPSSマッチング |
| decree-oracle | Go | スケジューラ・差分検出・通知ディスパッチ |
| decree-gateway | Go | REST/SSE API・BFF |
| decree-eye | TypeScript | Three.js WebGPURenderer + Sigma.js フォールバック |
| decree-migrate | Atlas | DDLマイグレーション（ジョブとして起動時に実行） |
データストア: PostgreSQL + Redis Streams
データモデル（イミュータブル設計）:
- fact table (INSERT ONLY):
scans, vulnerability_observations, vulnerability_disappearances
- resource table:
targets, vulnerability_instances, advisory_fix_versions
- projection table (唯一 UPDATE 可):
current_finding_status
スキーマ管理は Atlas に一本化。db/ 配下に正本を置き、atlas migrate diff で
migration を生成、decree-migrate ジョブで適用する。
全サービスはコンパイル言語またはビルドステップを持つため、コード変更後は
--build 付きの再ビルドが必須。古いバイナリが動き続けるとADRと実態が乖離する。
ワークフロー
以下のチェックリストをコピーして進捗を追跡する:
ADR作成進捗:
- [ ] Step 1: テンプレートと最新ADR番号を確認
- [ ] Step 2: 関連コンテナを再ビルド・起動
- [ ] Step 3: 起動状態を確認
- [ ] Step 4: ADRを日本語で執筆
- [ ] Step 5: ファイルに書き込み
- [ ] Step 6: 完了報告
Step 1: テンプレートと最新ADR番号を確認
cat docs/ADR/template.md
ls docs/ADR/ | sort | tail -5
ADR番号が会話中で指定されていればそれを使う。未指定なら最新番号の次を採番する。
テンプレートのセクション構成を把握してから執筆に入ること。
テンプレートの詳細な構成例は references/template.md を参照。
Step 2: 関連コンテナを再ビルド・起動
「ADRだけ書いて」と明示された場合はこのステップをスキップする。
実装内容から影響を受けるサービスを特定し、ピンポイントで再ビルドする:
docker compose up --build -d <service1> <service2>
docker compose up --build -d
スキーマ変更を伴う場合:
decree-migrate が atlas migrate apply を実行してから各サービスが起動する
依存関係になっている。スキーマ変更がある場合は migration ファイルが db/ 配下に
存在することを確認する。migration が未生成なら atlas migrate diff <name> で
生成してからビルドに進む。
ビルドが失敗した場合はログを確認してユーザーに報告し、修正を促す。
実装が動いていない状態のADRは信頼性がないため、ビルド成功を確認するまで執筆に進まない。
docker compose logs <service>
docker compose logs decree-migrate
Step 3: 起動確認
docker compose ps
sleep 5 && docker compose ps
docker compose logs --tail=50 <service>
確認ポイント:
decree-migrate が Exited (0) で正常終了していること- 各アプリケーションサービスの
State が Up / running であること
Exit / Restarting が出ていないこと- ヘルスチェックがあれば
healthy であること
異常があればユーザーに報告して止まる。
Step 4: ADRを日本語で執筆
執筆ガイドライン:
- テンプレートの構成に従う —
template.md のセクション見出しをそのまま使う
- 日本語で書く — コード・コマンド・固有名詞（サービス名、ライブラリ名、CVE ID等）は英語のまま
- OSSとして公開されるため、機微な情報を含めない:
- IPアドレス・ドメイン・ポート番号の具体値（
localhost:8400 程度はOK）
- 認証情報・APIキー・シークレット
- 個人名・組織名
- 意図・背景・トレードオフを重視する — 「なぜそう決めたか」が最も重要。コードの羅列ではなく、代替案を検討した上での判断根拠を書く
- 既存の記載を尊重する — 既に書かれているセクションは保持・拡充する
DECREE 固有の記述観点:
脆弱性ドメインのADRでは以下の観点を意識する:
- DECREE Score（CVSS × EPSS × Reachability の複合スコア）への影響
- スキャンパイプライン（SBOM生成 → OSV/NVD照合 → EPSS付与 → 分類）上の位置づけ
- イミュータブルデータモデル（fact / resource / projection）のどの層に影響するか
- Atlas migration の追加・変更が必要か
- 可視化（WebGPU/Sigma.js フォールバック）との連携
- リアルタイムモニタリング（ポーリング・SSE）への影響
執筆後のセルフチェック:
- テンプレートの全セクションが埋まっているか
- 機微な情報が含まれていないか
- DECREE の設計原則と矛盾していないか
- 日本語として自然に読めるか
Step 5: ファイルに書き込み
cat > docs/ADR/<対象ファイル>.md << 'DECREE_EOF'
<執筆した内容>
DECREE_EOF
cat docs/ADR/<対象ファイル>.md
Gitで管理されているためバックアップは不要。
Step 6: 完了報告
以下をユーザーに報告する:
- 再ビルドしたサービス名と起動状態
- 書き込んだADRファイルのパス
- ADRの主要セクションのサマリー（3〜5行）
git diff docs/ADR/ で変更差分の表示（オプション）
注意事項
- 複数サービスにまたがる実装では、各サービスの役割を明示してADRに記載する
- ADR番号が会話中に明示されていればそれを使い、
ls で確認しない
- decree-scanner (Rust) と decree-oracle/gateway (Go) で異なる設計判断がある場合は両方の観点を記述する
- 可視化（decree-eye）に関わる変更では、WebGPURenderer とSigma.js フォールバック双方への影響を記載する
- データモデル変更では、fact table への UPDATE 禁止原則を確認し、ADR内で「この変更は fact / resource / projection のどの層に影響するか」を明記する
- スキーマ変更を伴う実装では、Atlas migration ファイルの存在確認をビルド前に行う
