documentation-and-adrs
作成者 addyosmanidocumentation-and-adrs は、エージェントが意思決定を軸にした技術ドキュメントやADRを作成するのを助けます。アーキテクチャ、API、インフラ、認証、機能変更について、背景、制約、トレードオフ、却下した案、影響を整理して残すのに向いています。未来のエンジニアやエージェントのために、見栄えのよい要約ではなく、長く使える判断根拠が必要な場面に最適です。
このスキルは78/100で、エージェント向けの実用的なワークフロー指針があり、導入価値をユーザーが判断するための情報も十分にそろった、堅実な掲載候補です。意思決定ドキュメントとADR作成に明確に焦点を当てており、背景やトレードオフ、将来の保守性が重要な場面で、汎用的なプロンプトよりも適切な起点をエージェントに与えられます。
- アーキテクチャ判断、API変更、機能リリース、同じ説明の繰り返しに対して、明確な適用条件を示している。
- ADRの書き方が実務向きで、背景、制約、トレードオフ、代替案を重視している。
- 将来のエンジニアが実際に使えるドキュメントをエージェントが作れるため、ディレクトリ上の価値が高い。
- インストールコマンド、スクリプト、サポートファイルがないため、ユーザーはSKILL.mdのワークフローに依存する必要がある。
- 抜粋版には一部に途中で切れたセクションやプレースホルダーが見られるため、例外ケースまで含めた完全性は確認しにくい。
documentation-and-adrs スキルの概要
documentation-and-adrs スキルでできること
documentation-and-adrs スキルは、意思決定に焦点を当てた技術文書、特に Architecture Decision Records（ADR）を書くのに役立ちます。実際の役割は「もっと文書を書けるようにする」ことではなく、「チームがなぜその方針を選んだのか、どんな制約が重要だったのか、どの代替案を退けたのかを記録する」ことです。コードだけでは将来の保守判断を説明しきれない場面で特に有効です。
こんな人・こんな仕事に最適
このスキルは、エンジニア、テックリード、アーキテクト、そしてアーキテクチャ、API、インフラ、認証、データモデル、ユーザー向け機能変更に関する Technical Writing を行うチームに最適です。documentation-and-adrs を使うべきなのは、今の作業をきれいに説明することよりも、将来のエンジニアやエージェントのために長く残る文脈を残したいときです。
一般的なプロンプトと何が違うのか
通常のプロンプトでも読みやすい要約は作れますが、documentation-and-adrs skill は decision record、つまり文脈、制約、選択肢、トレードオフ、結果を軸にしています。この枠組みが重要なのは、弱いドキュメントの多くが実装の説明に終始し、将来の保守担当者が本当に必要とする「なぜその判断になったのか」を落としてしまうからです。
導入しない方がよいケース
インラインコメントの整理、軽い README の整形、一時的なプロトタイプ用ドキュメントだけが目的なら、このスキルは不要です。また、実装を見れば意図が明らかで、残すべき判断履歴もないような自明なコードパスにも向いていません。
documentation-and-adrs スキルの使い方
導入の前提と読み始める場所
documentation-and-adrs install の場合は、addyosmani/agent-skills リポジトリからスキルを追加し、最初に skills/documentation-and-adrs/SKILL.md を読みます。このスキルは単一のガイドファイルとして提供されており、補助スクリプトや参照ファイルはありません。そのため、ツール連携型のスキルよりも入力の質が重要になります。
環境が skill installation に対応しているなら、次を使います:
npx skills add addyosmani/agent-skills --skill documentation-and-adrs
その後、次を確認します:
skills/documentation-and-adrs/SKILL.md
documentation-and-adrs スキルに必要な入力
このスキルは、望む出力形式だけでなく、判断対象そのものが見える入力で最も力を発揮します。強い入力には、通常次の要素が含まれます:
- 提案されている変更内容
- 影響を受けるシステムや API
- パフォーマンス、コンプライアンス、コスト、期限、互換性などの制約
- 検討した代替案
- 想定される結果とリスク
- 想定読者と出力先。たとえば
docs/adr/やdocs/architecture/
弱い入力: “GraphQL への移行について ADR を書いて”
より強い入力:
- 現状: モバイルクライアント全体で versioning の問題がある REST API
- 必要な判断: 新しいプロダクト面で GraphQL を採用するかどうか
- 制約: 既存の REST endpoint は 12 か月維持、小規模な platform team、field-level の client flexibility が必要
- 代替案: 改善された REST conventions、tRPC、GraphQL gateway
- 判断の責任者: platform lead
- 出力: status、context、decision、consequences、rejected alternatives を含む ADR
よりよく使うためのプロンプトの作り方
よい documentation-and-adrs usage のプロンプトは、構成と判断の質の両方を求めるべきです。再現性の高い型は次のとおりです。
- 判断内容または文書の種類を明示する。
- プロジェクトの文脈と制約を与える。
- 検討した選択肢を挙げる。
- トレードオフ、前提、フォローアップのアクションを表に出すよう依頼する。
- 対象フォーマットを指定する。
例:
“Use the documentation-and-adrs skill to draft an ADR for choosing an authentication strategy for our B2B SaaS. Compare hosted auth, self-managed OAuth, and passkeys-first. Include context, constraints, decision drivers, rejected options, consequences, migration notes, and open questions. Audience is future backend and security engineers.”
実務チーム向けのおすすめワークフロー
実践的な documentation-and-adrs guide の流れは次の順番が使いやすいです。
- issue、PR、アーキテクチャメモ、チームチャットから事実を集める。
- 下書きの前に、agent に decision drivers を抽出させる。
- 初稿を見て、代替案の不足や明示されていない制約を確認する。
- 出力を、安定した命名と配置を持つ repository doc または ADR に仕上げる。
- 本番で判断が検証されたら、その記録を更新する。
このスキルは、具体的な source material と組み合わせた Technical Writing で特に効果を発揮します。逆に、どこにも書かれていない business 上または architecture 上の rationale を推測させようとすると、精度は大きく落ちます。
documentation-and-adrs スキル FAQ
documentation-and-adrs は Technical Writing の初心者向けですか？
はい、ただし前提として、その判断の裏にある事実にアクセスできることが必要です。このスキルは ADR や decision doc の構成づくりに役立ちますが、技術的判断そのものを代行するわけではありません。初心者は、何もないところから文書を作らせるより、会議メモ、issue リンク、ざっくりした pros-and-cons の一覧を渡した方がうまくいくことが多いです。
“write docs” と依頼するのと何が違いますか？
一般的な documentation プロンプトは、読みやすさの最適化に寄りがちです。documentation-and-adrs は、なぜこの方針を選んだのか、どんな制約があったのか、今後変更するときに読者が知っておくべきことは何か、という意思決定の保守性を重視します。この違いが最も効くのは、アーキテクチャ、公開 API、インフラの選定です。
このスキルの範囲はどこまでですか？
このスキルは、リポジトリ全体の文書システムでも、スタイル lint ツールでも、自動化付きの doc generator でもありません。プロセスと構成の指針を与えるものであって、ツールで強制されるスクリプトやテンプレートではありません。自動同期、標準の強制、公開フローが必要なら、それらを補う別ツールが必要です。
どんなときに documentation-and-adrs スキルを使うべきではありませんか？
些細な実装詳細、自明なリファクタ、重複したコードコメント、長期的な価値のない試作プロトタイプには使わないでください。チームがまだ本当の意味で意思決定していないなら、選択肢を比較するためにこのスキルを使うのは有効ですが、決定が済んでいないのに final な ADR が存在するかのように扱ってはいけません。
documentation-and-adrs スキルを改善するには
要約向けではなく、判断材料になる入力を渡す
documentation-and-adrs skill の出力を最も早く改善する方法は、判断の根拠になる証拠を渡すことです。退けた代替案、制約、想定される結果を含めてください。これらがないと、見た目は整っていても内容は一般論に寄ってしまいます。可能なら、design docs、PR description、RFC、incident review の抜粋も渡してください。
よくある失敗パターンを見極める
もっとも多い問題は次のとおりです:
- 理由の記録ではなく、実装の細部を繰り返している
- 代替案は並べるが、なぜ負けたのかを説明していない
- リスク、移行コスト、運用上の影響が抜けている
- 今日のレビュー担当者向けに書かれていて、将来の保守担当者向けになっていない
これらのどれかが見えたら、「decision drivers, rejected alternatives, and downstream consequences」に絞って修正を依頼してください。
初稿のあとに構成を詰める
最初の出力の後は、全部を書き直させるより、弱い部分を締めるよう依頼する方が効果的です。たとえば、次のようなフォローアップが有効です:
- “Make the tradeoffs more explicit.”
- “Add assumptions and what would change this decision.”
- “Separate immediate consequences from long-term maintenance impact.”
- “Rewrite for future engineers unfamiliar with this subsystem.”
リポジトリの慣習に合わせてスキルを調整する
documentation-and-adrs for Technical Writing をより有用にするには、ファイル命名、ADR 形式、文書の配置を agent に伝えてください。たとえば、docs/adrs/0007-auth-strategy.md のような連番 ADR を使うのか、docs/architecture/ 配下のトピック別ドキュメントなのかを指定します。プロンプトがリポジトリの文書規約に近いほど、生成後の手直しは少なくなります。