ハクソク

世界を動かす技術を、日本語で。

エージェントスキル

10時間前原文(addyosmani.com)

概要

  • シニアエンジニアの仕事は、コードの差分に現れない見えない作業が多い
  • AIコーディングエージェントはこれらのプロセスを省略しがち
  • Agent Skillsは、シニアエンジニアの標準的な工程をAIに強制する仕組み
  • ワークフロー重視、反合理化、検証必須など5つの設計原則
  • Googleのエンジニアリング文化やSDLCに基づいた実践的なガイドライン

シニアエンジニアの見えない仕事とAIエージェントの課題

  • シニアエンジニアの本質的な仕事は、スペック作成、テスト、レビュー、スコープ管理など、コードの差分（diff）には現れない作業
  • AIコーディングエージェントは、最短ルートで「完了」を目指すため、仕様確認やテスト作成、レビュー観点の配慮などを省略
  • これらの工程を飛ばすことは、シニアエンジニアが長年かけて避けてきた失敗パターン
  • Agent Skillsは、AIエージェントにこの「見えない作業」を強制するための仕組み

Agent Skillsの仕組みと「スキル」の定義

  • スキルはMarkdownファイルで記述され、必要なタイミングでエージェントの文脈に挿入
  • リファレンス資料ではなく、ワークフロー（手順とチェックポイント、明確な終了条件）が本質
  • エッセイ形式のルールのみでは実際の行動に結びつかないため、プロセス重視が重要
  • スキルごとに「やるべき行動」と「検証可能な証拠」が明記されている

SDLC（ソフトウェア開発ライフサイクル）との対応

  • 20種類のスキルが6つのライフサイクルフェーズ（Define, Plan, Build, Verify, Review, Ship）に整理
    • /spec: 何を作るか決める
    • /plan: 作業分割
    • /build: 実装
    • /test: 動作検証
    • /review: レビュー
    • /ship: 安全なリリース
    • /code-simplify: コード簡素化
  • GoogleやAmazonなど大手のSDLCと同様の流れ
  • AIエージェントはデフォルトで多くのフェーズを飛ばすが、Skillsは全工程を通過させる設計

5つの設計原則

  • プロセス重視: ワークフローを明示し、実行可能な手順とする
  • 反合理化テーブル: 「この作業は不要」という言い訳と、その反論をセットで記載
    • 例：「このタスクは小さいからスペック不要」→「受け入れ基準は必須」
    • 例：「テストは後で書く」→「“後で”は来ない。先に書く」
  • 検証必須: すべてのスキルは「証拠の提出」で終わる（テスト通過、レビュアー承認など）
  • 段階的開示: 必要なスキルだけを文脈にロードし、無駄な情報で性能劣化を防止
  • スコープ管理: 「頼まれた範囲だけ触る」を徹底。余計なリファクタや拡張は厳禁

Googleエンジニアリング文化との関係

  • Hyrum’s Law: API設計での互換性重視
  • テストピラミッドやBeyoncé Rule: テストファーストの徹底
  • DAMP over DRY: テストコードは明示的に
  • PRサイズ管理とレビューフレームワーク: 小さく、レビューしやすい単位で
  • Chesterton’s Fence: 理由が分かるまで削除禁止
  • トランクベース開発やShift Left: 早期検証・リリース分離
  • Code-as-liability: コードの最小化・保守性重視

Agent Skillsの利用方法

  • モード1: Marketplace経由でインストール
    • Claude Codeなどでコマンド追加し自動適用
  • モード2: Markdownを任意ツールに配置
    • Cursor, Gemini CLI, Codex, Aider, Windsurf, OpenCodeなどで利用可
  • モード3: ドキュメントとして読むだけ
    • スキル内容を自チームのガイドラインやレビュー基準に転用可能
    • まずは自分たちの課題に近いスキルから選び、ワークフロー整備を推奨

インストールしなくても盗むべきパターン

  • 反合理化の明文化
    • 「テストは後で」「小さすぎて設計不要」など、よくある言い訳とその反論を記録
  • プロセス重視への転換
    • 長文のリファレンス資料はワークフロー＋チェックリストに変換
  • 検証の強制
    • すべてのタスクの出口は「証拠の提出」とする

まとめ

  • Agent Skillsは、AIエージェントにシニアエンジニアの標準的な「見えない仕事」を強制するためのオープンな仕組み
  • プロセス重視・反合理化・検証必須・段階的開示・スコープ管理の5原則が、信頼性の高い開発を支える
  • Google等の実践知を体系化し、AI/人間問わず再利用可能なワークフローとして提供
  • 自チームの課題や文化に合わせて、部分的にでも「盗む」価値がある実践知

Hackerたちの意見

SEOやLLMOの観点から見ると、これらのスキルの発見性は名前を変えないと難しいよね。もしAddyがこれを読んでたら、どうやってSuperpowersと比べて提案するんだろう？
└
実際にどれくらいの人がsuperpowersを使ってるのか知りたいな。自分はsuperpowersが出る前からエージェント開発のシーンにいたけど、今は自分が作ったプロセスの50%以上がsuperpowersでカバーされてるんじゃないかと心配してる。GitHubのスターはもう信じられないけど、誰か教えてくれない？superpowersは本当に普及してるの？もし本当に価値があるなら、なんでBorisはまだその概念を統合してないの？
└
プラグインを通じて提供される缶詰のスキルの集まりみたいだね？
└
superpowersって実際に機能するの？メインのスキルファイルはあまり自信を与えてくれないよね。「もしスキルが自分のやってることに適用される可能性が1%でもあると思ったら、絶対にそのスキルを呼び出さなきゃいけない。」
└
これは、NextJSと競うためにReactJSっていうReactフレームワークを作るようなもんだね。
LLMをうまく使うには、欲しい結果を説明するのが一番だよ。それだけ。彼らはタスクを完了させるように訓練されてるから、明確な結果の方がプロセスよりもずっといい。もしLLMが失敗したら、結果を十分に説明できてなかったか、言ったことを誤解されたか、そもそもできなかったか（これは稀だけど）。一般的なエラーは、今後の似たようなタスクのためのコンテキストとしてエンコードすべきで、必要ないものをスキルに詰め込むのはやめよう。
└
確かに多くのスキルは大げさで必要ないと思う。でも、AIに正しいプロセスを与えることには大きな価値があるよ。superpowersスキルを使うと、Claudeが中程度や大きな変更に対してどれだけ効果的になるか見てみて。
└
スキルって再利用可能で共有できるコンテキストに過ぎないよ。要するにテキストなんだ。APIの使い方に関するドキュメントみたいなものには役立つし（自分的にはMCPよりもこっちの方がいいと思う）、合意が得られてないやり方にも使えるよ。例えば、remotionを使って動画を生成することができる。特定のタイプの動画を確実に生成するための有用なremotionスキルもあるよ。特定のスタイルのキャプションとかね。
└
ソフトウェアエンジニアリングの数十年で学んだことがあるとしたら、「明確な結果」を説明するのは簡単じゃないってことだね。多くの場合、4つの異なるドメインの人たちが協力しないと不可能だよ。だからプロセスが重要なんだ。ソフトウェアを「半標準化された」方法で構築することを可能にして、期待される結果に近づくための反復を可能にするんだ。それは時間とともに現れるかもしれない。確かに、自分がLLMを使う目的は、同じレベルの曖昧さや複雑な要求があるわけじゃないけど、プロセスの一部をスキップすることで最適化するのが、まさにAddyがこの記事で話してることなんだよね。
└
> LLMをうまく使うには、欲しい結果を説明するのが一番だよ。それだけ。彼らはタスクを完了させるために訓練されてるから、明確な結果を示す方がプロセスよりずっといい。複雑なことには当てはまらないけどね。彼らは指示に従う存在で、タスクの完了はその一面に過ぎない。情報が足りなくても、すごくやる気でタスクを完了しようとするけど、間違ったことをしちゃうこともある。タスクの完了をただ説明するだけだと、どんなに頑張っても見落としや、指定が不十分だったことに気づかないことがあるから、プロセスを追加するのが大事だよ。例えば、「関連するプロジェクトの慣習や情報を調べて、タスクをどうやって完了させるか考えて、あいまいな点を解決するために質問してね」とかね。こういうプロンプトは、新しいOpus 4.7の適応思考にも役立つから、タスクをちゃんと考えるようになるよ。
└
それはちょっと単純すぎる気がする。人間でも、何かを作ったりタスクを完了させたりするには、いろんな解釈や方法があるからね。エンジニアは覚えてくれるから、何度も同じことを繰り返さなくて済むんだ。スキルは、似たような繰り返しなしで結果を説明する方法だよ。
└
時々、人は自分が何を望んでいるのか分からないことがあるよね。私は小さく始めて、徐々に結果に近づくアプローチが好きなんだ。それから要約をお願いすることもあるし、その後に一般化を頼むこともあるよ。
みんながエージェントで遊んで、擬似的な生産性を感じながら1年以上無駄にしてるって気づくのが待ちきれない！
└
彼らを使ってまだお金を稼いでないの？
└
そうだね、紙の帳簿を使わなくなったことで失われた生産性と同じように、こういう「データベース」で遊ぶことになったんだよね。
└
ほんとその通り！すでに数ヶ月無駄にしたから、もうやめたよ :D
└
大事なのは、完璧なスキルやあれこれに時間をかけすぎないことだよ。LLMのゴミみたいなスキルで埋めてる人や、ルールをやりすぎてLLMを混乱させてる人をよく見る。まずはバニラを試してみて、気に入らないものがあったらスキルを作って、そのタスクのスタイルに合わせてLLMを使うようにするんだ。例えば、データベースの仕事はLLMにとっては混乱することが多いけど、制約をかけないと全然違うスタイルで作業しちゃう。エージェントは、ゴチャゴチャしたコードベースを引き継いでリファクタリングするのに信じられないくらい役立つよ。最近、10年以上前にPHPで書かれた古いコードのモンスターみたいなコードベースを引き継ぎ始めたんだ。ClaudeやCodexを使って、既存のレガシーストアフロントの大部分を移植できたし、10-20k LOCのメガコントローラーロジックを再利用可能なリポジトリ/サービスパターンに集中させるための基盤を作ったよ。以前は何年もかかってたことが、1ヶ月もかからずにできるようになった。
└
俺はそれをMinecraftの自動化みたいに扱ってるんだ。楽しみのためにやってるし、時間をつぶすためにね、ハハ。エージェント的なワークフローはまだそこまで進んでないけど、AIと並行して作業するためにスキルを手動で呼び出して使うのは確かにいいよね。うちの会社は今、サンドボックスにすごく力を入れてて、安全なスキルを持つことが大事だと思ってる。機能開発はまだうまくいってないけど、レビュー用のスキルやGrafanaのスキルは結構しっかりしてるよ。
└
彼らは自分に嘘をついて、それを否定するんだ。
└
この意見にはちょっと興味があるんだ。善意で議論してるけど、AIやエージェント、ハーネスを使う人たちが機能を出荷しないっていうのが一般的な前提なの？私たちは去年の9月頃からClaude Codeを使っていて、その効果をちゃんと追跡できてるよ。実際に出荷した機能がプロダクションで使われてるからね。インフラ側もビジネスロジックの実装も含めて。フロントエンドとバックエンドの両方で。あまり時間を無駄にしてるとは思わないけど、確かにこの投稿のほとんどはただの戯言だと思う。AI開発は世界中の多くの企業で進んでることだしね。
└
これは私たちの業界における別のマイクロサービスの瞬間になるだろうね。
└
ある程度の懐疑心は理解できるし、AIがあらゆる理由で悪いと根本的に信じることもあるけど、こういう発言の背後にある確信にはますます困惑してる。どうしてそんなにAI開発が運命づけられていると確信してるの？私の経験とは全く一致しないし、君がAIコーディングの確実な破滅についてそんなに強い確信を持つに至った経験は何なのか気になる。AIが道徳的に悪いという哲学的な信念だけなの？それとも実際にAIを使って何かを作って、十分にその領域を探求したと感じているの？私は30年以上毎日コードを書いていて、20年以上はプロとしてやってる。流行が来ては去るのを見てきたし、私のやり方を何度も変えるような実際の進展も見てきた。AIを使ってプロジェクトを進めるほど、これはソフトウェアの生産方法やコンピュータの使い方において持続的で根本的な変化だと確信するようになってきた。AIが良くなっていくのを見て、自分もそれを使って実際の仕事をこなすスキルが上がっていくのを感じている。実際のプロダクションワークロードでテストされた仕事をね。これが起こっていることを嫌うこともできるし、AIとの作業の感覚を嫌うこともできるけど、それが人々にとって実際の価値を提供していることや、実際の仕事をしていることを意味するわけじゃないよ。
└
俺は出力を測定するプロジェクトに取り組んでる。これには「擬似」なんてないよ。
過去にこれらの大きなエージェントスキルセットを試したけど、やることが多すぎて時間の無駄だと感じたよ。vimみたいに、コミュニティから選んで使う方がいいことが多い。スキルはすごく個人的なもので、開発者や開発チームによって違うからね。だから、他の人の設定を一括インストールするんじゃなくて、自分の設定の参考にする方がいいよ。
なんでみんな自分の仕事を奪う方向に進んでるの？これらの「スキル」がそうするわけじゃないけど、原則的にね。これは労働からの疎外を大規模に体験してるみたい。
└
いろんな人がグローバル最適化ゲームをやってるね。誰でも好きな（生産レベルの）ソフトウェアを手に入れられる世界。
└
だって、私たちは何十年も前から仕事の大部分を自動化してきたから。そうじゃなかったら、みんな仕事をできるだけ非効率的にやろうとして、仕事にかかる時間を最大化しようとすることになると思うけど、それはあまり良いアイデアじゃないよね。人間は、一定の出力を得るために必要な作業量を最小限に抑えることをずっと続けてきたんだ。それが文明だよ。手で鍬を使って農業に戻るべきなの？個別に点灯する街灯に戻るの？自動化が遅れる社会は貧しくなって、最終的には滅びる。そこに生まれた人たちも生産性の高い場所に移住することを選ぶから。東欧で起こったことだし、アーミッシュにも起こってる。移住がある貧しい社会にはいつもそういうことが起きる。少ないもので多くを成し遂げるのは、ずっとワクワクすることだよ。
└
だって、仕事を失う人は市場に適応できない人が多いから。今は全てがどの方向に進んでいるのかはっきりしないから、みんなランダムなエージェントにデータを渡して、コンテキストの保存やアクセスの仕方、プロンプトの再利用などを試行錯誤してるんだ。これらの多くは、次のモデルの波に深く統合されるかもしれないから、1年後には役に立たないかもしれないけど、開発の最前線にいることがこの分野で働く楽しみの一部だよ。
└
今、人々は生産性の名のもとにAIのノートテイキング機能を使うように促されている。労働者は、仕事に関連するすべてのコンテキストの合計に過ぎない。このコンテキストを整理、確認、整理するのは、置き換えられることを求めているようなものだよね。
└
ソフトウェアエンジニアが6ヶ月後には存在しない30ヶ月目。
└
コンピュータープログラマーとして、この考え方が理解できないな。俺の人生は、コンピューターに仕事をさせて、人間がそれをしなくて済むようにすることだったから。書かれたソフトウェアは、誰かの仕事を奪うためにあるんだよね。君も作る自動化について、そう感じることある？昔ながらのシステム管理者の中には、インフラの自動化の進展に対してそう感じている人もいたし、手作業でやっていた仕事をスクリプトやシステムでやるのが嫌だって言ってた。俺のチームは、30,000台のサーバーで自動的にパッチを適用する自動パッチシステムを作ったんだ。これで、システムを自律的に運用から外したり戻したりできて、全てのプロセスがハンズフリーになった。以前は、そのプロセスを手動で運用するための専任チームがいたんだ。自動化することで彼らの仕事を奪ったのかな？確かに、そういう面もある。でも、他にやるべき仕事があったし、今はそれをやれるようになった。プログラミングやコンピューター、テクノロジーが好きな理由は、まさに俺たちのために仕事をしてくれるからなんだよね。俺のユートピアは、ロボットが全てのハードワークをしてくれて、人間が好きなことをできる世界。AIはその実現に一歩近づけてくれてると思うし、俺は、ロボットが仕事を奪うことで全世界が利益を得られるようにする方法を考えることに集中したい。富裕層だけじゃなくてね。人間が本当にやりたくないことをするために、十分な仕事を残しておくことに気を使うよりも。
└
突然「トップ」に加速された、あまり良くない開発者たちが一番それを求めている気がする。俺が知ってる良い開発者たちは、もう少し慎重に受け入れてるね。
これはまさに「蛇油」だね。読む価値はあるけど、結局は蛇油。理由はこうだ：スロットマシンは、AGENTS.mdやmemory.md、何十ものスキルのマークダウンに書かれたハードな要件を簡単に無視できる。ほぼ確実にね。これらのアプローチは、LLMが厳密で完璧なルールに従う存在で、問題はルールを明確に指定できないことだと見せかけている。それはLLMの動作に関する根本的な認識の欠如だよ。結局、信頼性は低いけど、より信頼できる選択肢は人間のレビューと監視だけ。もしかしたら、二人の人間が順番に行うことになるかも。その他は全部蛇油だけど、その時点で約束された生産性の向上も蛇油だって気づくよ。コードを読むことやメンタルモデルを構築するのは、メンタルモデルを持ってそれをコードに書くよりもずっと難しいからね。
└
君の言うことは理論的には全部可能だし、同意するよ。ただ、ここ数ヶ月spec-kit（基本的にこのスタイルのAIの使い方）を使ってきたけど、実際にはすごく効果的だったんだ。素晴らしいものを作っていて、君が言ってるような仮定の問題には一切直面してない。最終的にそうなる可能性はあるけど、今はまだ慎重に見てる。でも、実際に使ってみて長い時間が経つと、蛇油だとは簡単に否定できないよ。私は30年以上プログラマーをやってきて、何が実際に機能するかをよく理解してると思う。
└
人間も、君が指定した厳しい要件を定期的に無視するし、同様にレビューが必要だよね。それでも、プロセスやレビューを通じて人間の出力の信頼性を高めることができてるし、俺たちが使っているほとんどの方法は、人間の信頼性の問題を減らすための経験から来ているんだ。人間は信頼性を確保するのが notoriously 難しいからね。
これがspec-kitよりも良い/違う点は何？すごく似た哲学を持ってるみたいだけど、一緒に働けるのかな？それとも単に重複するだけ？ https://github.com/github/spec-kit
> スキルは、状況に応じてエージェントのコンテキストに注入されるフロントマター付きのマークダウンファイルです。LLMが状況に応じて必要だと判断したときに。 > それはワークフローです：エージェントが従うステップのシーケンスで、証拠を生み出すチェックポイントがあり、定義された終了基準で終わります。LLMが従うことを決定できるステップのシーケンスです。
スーパーパワーとこれの違いは何？俺は数ヶ月間スーパーパワーを使ってて、ほんとに助かってる。でも、やっぱり90/10の法則が当てはまる。10%の確率でバカな決定を出すから、仕様は常に確認した方がいいよ。
エージェントスキルは、「五つの設計決定 [が] 支持するもの」から成り立っている。そして、オープンデザイン（昨日のHNのフロントページ）は「六つの支えるアイデア」によって支えられている。これらのプロンプトライブラリの文書化の仕方に似ているのは、偶然ではない気がする。