メニュー
Alt の Architecture Decision Record を日本語で `docs/ADR/NNNNNN.md` に書き起こす。番号採番、frontmatter（title/date/status/tags/affected_services/aliases/supersedes）、Context・Decision・Consequences の書き分け、wikilink 形式、OSS 公開向けの情報衛生を扱う。実装が一段落して決定を記録するときに使う。ユーザが「ADR書いて」「ADRにまとめて」「ADRに記録して」「実装が終わったのでドキュメントに」と言ったとき、または設計上の判断を伴う変更を終えたときに使う。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
Drive Alt changes test-first in outside-in order — E2E (Playwright/Hurl) → CDC (Pact) → Unit (RED-GREEN-REFACTOR) — and close with a local CI parity sweep (format/lint/type/security) for every touched microservice. Use when implementing a feature, fixing a bug, or refactoring, when deciding what test to write first, or when the user says "TDDで". Also use before declaring work complete, since "tests pass" is not "CI will pass".
Interrogate a plan against the project's documented decisions and domain language — challenging fuzzy terms, cross-referencing the code, and surfacing where the plan contradicts an existing ADR or canonical contract. Use when the user wants a plan stress-tested against what the project has already decided, rather than in the abstract. Prefer plain grill-me when there is no documented model to test against, and plan-context-loader when the goal is to gather vault context rather than be questioned.
Hunt for deepening opportunities — shallow modules whose interface costs as much to learn as their implementation saves — and present them as a visual before/after report, informed by the decisions already recorded in docs/ADR/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, reduce the cost of understanding a subsystem, or make code more testable. Use clean-architecture instead when the question is whether a specific change violates Alt's layer rules.
設計・計画タスク時に、Obsidian vault から関連 ADR・contract・review・runbook を 必要最小限だけ集めて計画の精度を上げる。 次のときに使う: - 「計画を立てて」「設計して」「プランを作って」 - ADR や過去の決定を確認したい - Knowledge Trail / Knowledge Home や reproject-safe / immutable 設計が絡む
Alt の Go 規約を適用する。エラーラップ、context 第一引数、slog、テーブル駆動テスト、http.Server の 4 タイムアウト、Redis Streams の XACK/XAUTOCLAIM 対、fail-fast 設定を扱う。Go のコードを書く・直す・レビューするときに使う。ユーザが「Go」や規約名に触れなくても、Go サービス（alt-backend, auth-hub, pre-processor, search-indexer, mq-hub, rag-orchestrator, altctl）の実装・修正に入るなら使う。
Alt の Python 3.14+ 規約を適用する。型ヒント必須と Pyrefly、具体例外と原因チェーン、Pydantic/frozen dataclass の境界保護、asyncio と同期推論の分離、spawn プロセスプール、起動時 fail-closed を扱う。Python のコードを書く・直す・レビューするときに使う。ユーザが「Python」や規約名に触れなくても、Python サービス（news-creator, tag-generator, metrics, recap-subworker, recap-evaluator, acolyte-orchestrator）の実装・修正に入るなら使う。
| name | alt-adr-writer |
| description | Alt の Architecture Decision Record を日本語で `docs/ADR/NNNNNN.md` に書き起こす。番号採番、frontmatter（title/date/status/tags/affected_services/aliases/supersedes）、Context・Decision・Consequences の書き分け、wikilink 形式、OSS 公開向けの情報衛生を扱う。実装が一段落して決定を記録するときに使う。ユーザが「ADR書いて」「ADRにまとめて」「ADRに記録して」「実装が終わったのでドキュメントに」と言ったとき、または設計上の判断を伴う変更を終えたときに使う。 |
| allowed-tools | Bash, Read, Glob, Grep, Edit, Write |
| argument-hint | [決定の対象] [--only-docs] |
2 つのフェーズを順に実行する。
docs/ADR/NNNNNN.md を日本語で追加するこのスキルはデプロイを行わない。 本番反映はユーザの明示指示に基づく別作業であり、手順は
docs/runbooks/deploy.md に委ねる（§4 参照）。
ADR は「動いた状態」を固定する行為なので、最低限のテストで動作確認を先に済ませる。 コンテナの再ビルド・再起動は行わない。
| 変更の種類 | 最低限回すコマンド |
|---|---|
| Go service | go test ./... |
| Rust service | cargo test |
| TypeScript / Svelte (alt-frontend-sv) | bun run check && bun test |
| Python (news-creator 等) | uv run pytest |
| ドキュメント・scripts のみ | 該当テストだけ（例: bash tests/scripts/run.sh） |
テストが落ちていたら ADR は書かず、ユーザに原因を報告して止まる。ADR は動いた実装の決定記録であり、 憶測を書く場所ではない。
ls docs/ADR/ | sort | tail -1 # 最新番号を確認
最新 +1 の 6 桁ゼロ埋め（例: 000750 → 000751）をファイル名にする。docs/ADR/template.md を Read で
開き、そのセクション見出しをそのまま使う（勝手に増減しない）。
| フィールド | 値の決め方 |
|---|---|
title | 動詞始まりの行動指向の一文。ADR 番号は含めない |
date | YYYY-MM-DD（当日） |
status | 原則 accepted。新 ADR 自身を superseded にしない（置換される側の status はグラフ投影） |
tags | §2.4 の許可タグから最大 5 個 |
affected_services | サービス名と変更概要を 1 行/件で列挙。バッククォートや : を含む項目はシングルクォートで囲む（厳密 YAML） |
aliases | ADR-NNN と ADR-000NNN の 2 形式を必ず両方入れる（Obsidian のリンク解決用） |
supersedes | 本 ADR が既存 ADR を完全置換する場合のみ、旧 ADR 番号（6 桁）を列挙。置き換えないならキーごと省略する（空の supersedes: - stub は dangling 判定を汚す）。新 ADR 側にだけ書き、逆辺は DocDag が算出する |
template.md を尊重する。 Context / Decision / Consequences (Pros, Cons/Tradeoffs) /
Related ADRs の順が基本[[000NNN]] タイトル 形式で列挙する。Obsidian のグラフビューと
バックリンクはこの形式でしか機能しないため、ADR-000NNN (タイトル) 形式は使わないarchitecture, clean-architecture, connect-rpc, performance, security,
database, migration, pgbouncer, frontend, backend, api, rss, search,
caching, authentication, docker, networking, ci-cd, testing, refactoring,
bugfix, monitoring, logging, ai, rag, recap, nats, queue, 3d-graphics
この外のタグを増やしたくなったら、ADR ではなく docs/CLAUDE.md を先に更新する。
Alt は OSS として公開されている。以下を含めない。
localhost:XXXX と compose サービス名は OK。
Write ツールで docs/ADR/NNNNNN.md を作る。heredoc や cat > ... は使わない。
supersedes を書いた場合は次を実行し、循環・dangling・空 stub・status ドリフトが無いことを確認する
（非ゼロ終了なら frontmatter を直す）。
docdag validate
置き換え対象の旧 ADR の status は同じ commit で superseded に揃える（status 投影の例外）。
ADR とコードは同じ commit にまとめる。
git add -A
git commit -m "<英語の 1 行メッセージ>" # Co-Authored-By は付けない
git push はしない。push はユーザの明示指示があったときだけ、ユーザ自身が行う。
docs/ADR/NNNNNN.md）とタイトルdocdag validate の結果（supersedes を書いた場合）ユーザが ADR とあわせて明示的にデプロイを指示した場合のみ、docs/runbooks/deploy.md の手順に従う。
このスキルの中で ./scripts/deploy.sh や c2quay を独断で実行しない。「ADR 書いて」はデプロイの
許可ではない。
DB マイグレーションが絡む場合は必ず migrate → deploy の順。逆にするとアプリが新スキーマを期待した
まま旧スキーマで起動し、healthcheck が通らない。
| ユーザ発話 | §1 実装確認 | §2 ADR 執筆 |
|---|---|---|
| 「ADR だけ書いて」「docs だけ」 | skip | run |
| 「実装まとめて ADR 書いて」 | run | run |
| ドキュメント / scripts のみの変更 | 該当テストのみ run | run |
docs/ADR/template.md — セクションと frontmatter のソースdocs/runbooks/deploy.md ([[deploy]]) — デプロイ手順の完全版docs/runbooks/pact-broker-ops.md ([[pact-broker-ops]]) — Broker 運用docs/CLAUDE.md — vault 全体の編集ルール