architecting-solutions

architecting-solutionsスキルの概要

architecting-solutionsでできること

architecting-solutions は、Claude Code向けに用意された、アーキテクチャ設計とソリューション設計のための構造化ワークフローです。
「請求システムを設計したい」「移行計画を立てたい」といった粗い依頼を、要件整理・トレードオフ整理・実装を見据えた技術設計へ落とし込み、最終的にプロジェクトの docs/ 配下へ文書として残すのに向いています。

architecting-solutionsが向いている人

このスキルは、一般的なブレインストーミング回答では足りないエンジニア、テックリード、スタッフエンジニア、AI支援で開発を進めるビルダーに特に適しています。
たとえば、システム設計、移行計画、リファクタリング、機能アーキテクチャ設計、Requirements Planning のように、制約を明示しながら推奨案を文書化したい場面で使いやすいです。

実際に解決したいジョブ

ユーザーが architecting-solutions に期待する成果は、主に次の3つです。

1. あいまいな依頼を具体的な技術計画に変えること
2. 複数の選択肢をトレードオフ込みで比較すること
3. 実装に引き継げる、再利用可能なPRD風アーキテクチャ文書を残すこと

そのため、プロジェクト固有の前提や文脈が重要な場合、単発の「このシステムを設計して」プロンプトよりも architecting-solutions のほうが実用的です。

普通のプロンプトと違う主な強み

architecting-solutions の価値は、ワークフローがきちんと整理されている点にあります。

• 最初に要件の確認から入る
• 既存コードベースのパターンや制約を分析する
• チャット回答だけで終わらず、文書として成果物を残す
• 結果を明示的に docs/ に書き出す

注意したいニュアンスとして、リポジトリの説明では、依頼が明確に PRD を求めている場合は PRD 専用用途に使わないほうがよいとされる一方で、スキル自体は PRD 風のアウトプットも生成します。実運用では、純粋なプロダクト探索よりも、実装文脈を伴う技術設計や Requirements Planning に最もフィットします。

architecting-solutionsが強くハマるケース

次のような用途では architecting-solutions が有力です。

• 新機能や新しいサブシステムのアーキテクチャ設計
• 移行やリファクタリングの計画
• 既存コードベースを前提にした技術設計
• トレードオフ分析を伴う複数案の比較
• 技術的なスコープや制約が重要な architecting-solutions for Requirements Planning

このスキルを使わないほうがよい場面

次のような要件であれば、architecting-solutions は使いどころが違います。

• 軽いアイデア出しだけをしたい
• アーキテクチャの深掘りが不要な、プロダクト寄りのPRDだけが欲しい
• バグ修正の進め方を整理したい
• 設計なしでコード生成だけしたい
• 技術制約よりも、事業上の優先順位でほぼ決まる意思決定をしたい

architecting-solutionsスキルの使い方

インストール時の前提とリポジトリ内の場所

このスキルは zhaono1/agent-playbook の中の skills/architecting-solutions にあります。

実用的なインストールコマンドは次のとおりです。
npx skills add https://github.com/zhaono1/agent-playbook --skill architecting-solutions

また、ドキュメントでは、インストール後の典型的な配置先として次も案内されています。
~/.claude/skills/architecting-solutions/

最初に読むべきファイル

まず評価するなら、次の順番で読むのがおすすめです。

1. skills/architecting-solutions/SKILL.md
2. skills/architecting-solutions/README.md

特に SKILL.md には、発火条件、ワークフロー、利用可能なツール、そして成果物を docs/ に書き出す要件など、運用上の重要情報がまとまっています。

実際のarchitecting-solutionsの発火パターン

リポジトリの例は、次のようなシンプルで直接的な英語プロンプトです。

• “Design solution for a new billing system”
• “Provide an architecture design for multi-tenant analytics”
• “Technical design for a data migration plan”

つまり、architecting-solutions usage はコマンド操作中心ではなく、プロンプト起点で使うタイプです。
反応のきっかけになるのは、ソリューション設計、アーキテクチャ設計、技術設計、移行計画、機能レベルの技術計画といった意図そのものです。

出力品質を大きく左右する入力情報

architecting-solutions は、次の情報があると出力の質がかなり上がります。

• システムの目的
• ユーザー特性やワークロード
• 厳守すべき制約
• 既存の技術スタック
• 非機能要件
• デリバリー上の境界条件

良い入力例:
“Use architecting-solutions to design a multi-tenant analytics ingestion service for our Node.js/Postgres stack. We ingest 50M events/day, need tenant isolation, 99.9% uptime, GDPR deletion support, and rollout in two phases without breaking current APIs.”

この入力が有効なのは、スケール、技術スタック、制約、信頼性目標、段階的ロールアウト条件といった、アーキテクチャ判断を実際に変える要素が入っているからです。

あいまいな依頼を強いプロンプトに変える

弱い例:
“Design an analytics system.”

より強い例:
“Use architecting-solutions to propose 2 architecture options for a multi-tenant analytics platform in our existing Python + Kafka + ClickHouse environment. Include ingestion, storage, query path, tenant isolation, observability, and migration risk. Recommend one option and write the final design to docs/analytics-architecture.md.”

後者のほうが、選択肢の質、比較の深さ、成果物の形式が明確になり、architecting-solutions をより活かせます。

実案件でのおすすめワークフロー

実務で使う architecting-solutions guide は、次の流れが扱いやすいです。

1. まず問題設定を渡す
2. スキルに確認質問をさせる
3. 関連するリポジトリ領域を指定する
4. 2〜3案の明示的なトレードオフ比較を求める
5. 推奨案を出させる
6. 最終的な markdown を docs/ に書かせる
7. 実装開始前に抜け漏れをレビューする

特に Requirements Planning では、この流れによって探索、制約整理、最終設計を一つの雑な回答にまとめず、段階的に分けて進められます。

このスキルが明確にこだわっていること

リポジトリ上で最もはっきりした方針は、成果物の保存先です。最終的なPRD風ドキュメントは、隠しファイルや一時メモではなく {PROJECT_ROOT}/docs/ に書く前提になっています。
チームで設計文書の置き場所が別に決まっているなら、エージェントが既定のパスに寄らないよう、最初に明示しておくべきです。

コードベースを踏まえた設計にするための最適な指示

すでにリポジトリを開いているなら、どこを見てほしいかを具体的に伝えるのが効果的です。
“Use architecting-solutions for Requirements Planning on our auth overhaul. Review services/auth/, docs/current-architecture.md, and infra/terraform/ first. Match existing deployment patterns unless there is a strong reason not to.”

これは重要です。というのも、このスキルは、提案前に文脈や既存パターンを分析することを前提に設計されているからです。

想定されるアウトプットの形

ワークフローから考えると、architecting-solutions の出力には通常次が含まれます。

• 要件の明確化
• 文脈と制約の分析
• 提案アーキテクチャ
• トレードオフ
• 実装につなげやすい markdown ドキュメント

もっと軽い回答がほしいなら、その旨を先に伝える必要があります。指定しない場合は、即答型の助言よりも、文書成果物を優先する出力になりやすいです。

よくある導入時のつまずき

最大のボトルネックは、スコープがあいまいなことです。制約を示さずにアーキテクチャ設計を依頼すると、出力はどうしても汎用的になりがちです。
スキルの良し悪しを判断する前に、具体的な規模感、システム境界、そして cost vs speed、consistency vs latency、reuse vs rewrite のような少なくとも1つの明確なトレードオフを含む依頼で試すのがおすすめです。

architecting-solutionsスキルのFAQ

architecting-solutionsは初心者にも向いていますか？

はい。ただし、初心者でも対象システムの前提をある程度理解していることが望ましいです。
このワークフローは、要件確認と構造化思考を強制してくれるので助けになりますが、トレードオフの妥当性を判断するのは難しい場合があります。そのため、経験豊富なエンジニアのレビューと組み合わせる使い方が最も安全です。

これはPRDスキルですか、それともアーキテクチャスキルですか？

実運用上は両方の性格を持ちますが、軸はアーキテクチャ寄りです。
リポジトリのメタデータでは architecting-solutions は技術的なソリューション設計・アーキテクチャ設計スキルとして位置づけられており、一方でワークフロー上は PRD 風の markdown 成果物も出力します。純粋なプロダクトマネジメント用PRDではなく、技術設計に駆動された文書が必要なときに使うのが適切です。

architecting-solutionsは普通の「design this」プロンプトと何が違いますか？

通常のプロンプトは、見栄えはよくても文脈の薄い回答になりがちです。
一方で architecting-solutions skill は、要件確認、コードベース確認、選択肢比較、保存可能な設計文書の生成まで含む、再現性のある進め方を求める場面に向いています。

architecting-solutionsの導入で追加ツールは入りますか？

特別な補助スクリプトや専用リソースフォルダが必要だとは、ここでは示されていません。
architecting-solutions install は基本的に、agent-playbook リポジトリからスキルを追加し、その後 Claude Code 上で適切なプロンプトとリポジトリ文脈を与えて呼び出すイメージです。

architecting-solutionsをRequirements Planningに使えますか？

はい。architecting-solutions for Requirements Planning は、要件が技術制約、移行の現実、アーキテクチャ選択に左右される場合にはかなり相性がよいです。
一方で、初期の市場検証や、純粋にビジネス側だけで要件を固める段階にはあまり向いていません。

architecting-solutionsを使わないほうがいいのはどんなときですか？

次のようなケースでは見送りが妥当です。

• プロダクト戦略メモが欲しい
• 短い実装チェックリストで十分
• デバッグ支援が欲しい
• コードだけ返ってくればよい
• アーキテクチャ分析のないPRDが欲しい

architecting-solutionsスキルを改善する方法

広い目標より、強い制約を与える

architecting-solutions の結果を改善する最も効果的な方法は、ふわっとした要望を、設計判断に効く制約へ置き換えることです。

• トラフィック規模
• レイテンシ目標
• コンプライアンス要件
• デプロイ環境
• 後方互換性
• コスト上限
• 納期

こうした入力のほうが、「scalable」や「robust」のような抽象的な目標より、はるかに鋭いトレードオフを引き出せます。

いきなり結論を求めず、先に選択肢を出させる

最初の回答が狭すぎると感じたら、次のように依頼します。
“Give me 2–3 viable architectures first, with trade-offs and failure risks, before writing the final recommendation.”

こうすることで、単一パターンに早く収束しすぎるのを防げます。

適切なコードと文書の場所を具体的に指す

よくある失敗は、ローカルの慣習を無視したアーキテクチャ案が出ることです。改善したいなら、次のようにパスを明示してください。

• services/
• apps/
• docs/
• infra/
• 現在の ADR や設計文書

既存システムでは、プロンプトに説明文を足すより、こうした実パスを渡すほうが効くことが少なくありません。

成果物のファイルを明示する

再利用可能な文書にしたいなら、ファイル名と想定読者を指定すると効果的です。
“Write the final design to docs/payment-migration.md for backend engineers and reviewers.”

これはスキルの既定挙動と整合し、フォーマットや深さのあいまいさも減らせます。

最初の汎用ドラフトは、具体的な追質問で直す

最初の出力に対して、単に「もっと良くして」とは言わないほうがよいです。代わりに、改善点を明確に指定します。

• 運用リスクを追加する
• 移行戦略を比較する
• ロールバック計画を含める
• データモデルへの影響を示す
• チーム単位で依存関係を整理する
• 検証が必要な未知点を明記する

ピンポイントな反復のほうが、最初からやり直すより速く文書品質を上げられます。

もっとも起きやすい失敗パターンに注意する

architecting-solutions の主な品質リスクは次の4つです。

• 制約の指定不足
• 実際のコードベースから切り離されたアーキテクチャ
• トレードオフ分析が弱いのに自信だけ強い推奨
• 実装計画には広すぎるPRD風アウトプット

この4点は、多くの場合、リポジトリのパス、厳しい制約、比較セクション必須という条件を与えることで修正できます。

レビューループでarchitecting-solutionsを強化する

最も実用的なのは、2パス運用です。

1. architecting-solutions で初回設計を作る
2. 足りない制約がないか確認し、推奨案に対して反証的にレビューする

追質問としては、たとえば次のようなものが有効です。

• “What assumptions would most likely break this design?”
• “What is the cheapest acceptable version?”
• “What changes if we optimize for 3-month delivery instead of long-term scale?”

こうした問いを重ねることで、単なる文書生成ツールではなく、実務に使える設計レビュー支援として architecting-solutions を活かせます。