まえおき
遅れながらも2026年3月はガッツリClaudeCodeと戯れる事が出来、
それを通じてAI活用について色々考えることが出来たので、
自分用メモとして思考整理、言語化したものをアウトプット。
この記事は主に、一番手に馴染んでいるウォーターフォール開発という道具を、
ClaudeCodes Skillsとハーネスエンジニアリングの考え方で見直せないかな？
って話です。
自己紹介
AI活用についての記事、ポジショントークになりがちで、
「おまえ誰やねん」っての個人的に気にしちゃうので...ざっくり自己紹介
- キャリア10年ちょいのミドルエンジニア
- 学生時代からパソコン大好き
- 00年代後期はCとかJavaとか
- 10年代前半は大学でオブジェクト指向、LAMPからのDocker、k8sの世代
- 2015年くらいキャリア開始、組み込み系でガッツリSE
- C++書いたり組み込みOSのカーネル読んだり
- 開発手法はゴリゴリのウォーターフォール
- 2020年くらいからソシャゲサーバーサイドでテックリード
- GCP、Golang、SpannerでProfessional Cloud Architect取ったり
- 開発手法はウォーターフォールライクな、なんちゃってアジャイル
- に、メテオフォールのエッセンスを加えて
- 2026年現在、Web系サーバーサイドで社内システム携わってます
- 普段はLLM使われエンジニアを名乗ってます
ClaudeCode Skills
手順書をSkillにする
僕はClaudeCode Skillsについて、
タスクのゴールと進め方を自然言語でMakrdownに書き起こしただけだと認識しました。
なのでSkill化は今までになかった特別な作業だとは考えて無く、
手順書のフォーマットが変わっただけだと考えています。
（そして構造化されたMarkdownペライチなので、
Claudeにロックインしてしまうような特別な機能でもないですね）
SE、SIerを経験した人は分かると思いますが、とにかく手順書を作り暗黙的を形式知にしてきましたよね？（環境構築手順書とかリリース手順書とか）
なのでまずは既にある手続き的な手順書をSkill化し、
今後作る手順書はSkillとして作りチームでメンテナンスするのが良さそうです。
開発ステップをSkillにする
※以下を参考にさせてもらっています
ここからは実際の開発サイクルをSkill化していく話。
以下、ウォーターフォールの図です。
テスト・結合テストなどQA文脈は話が複雑になり、
それだけで1記事書けちゃうほど膨れ上がるので割愛します。
が、以下のイメージです。
- 設計→テスト項目、要求仕様書→結合テスト項目のV字になる
- テスト項目作成・結合テスト作成は後述のWhyドリブン
- テスト実施・結合テスト実施は後述のMustドリブン
上記はINPUTとOUTPUTが明確なので以下の方針でSkill化出来ると考えました。
- 要求が大きい時は設計のタイミングで機能分割
- 機能のスコープが明確になっている仮設計も作成
- 設計から開発タスクを分割（Task.md）
- 開発SkillはTask.mdをINPUTに取る
各工程のOUTPUTは有人レビューを実施する想定です。
Skillは更に細分化することも出来ますし、
分割するタイミングを変えたり他にも逆にまとめることも出来ると思います。
が、僕にとってはウォーターフォールの工程が慣れ親しんだ道具になっているので、
この単位でSkillにするのが成果物をイメージしやすくレビューしやすいと考えています。
ただ工程ごとにSkillの作り方は一緒なのでしょうか？
Skillの書き方は大枠（アウトライン）として２通りのパターンがあると考えました。
Mustドリブン と Whyドリブン
以下の考え方がとても自分の中でしっくりしたので引用させてもらいます。
Must-driven（従来型） Why-driven（推奨） "ALWAYS validate before submission" "Validation prevents API errors that waste tokens and frustrate users" "NEVER skip the formatting step" "Consistent formatting ensures the viewer can parse results correctly"
「両側が崖の狭い橋」ではMust-driven、「障害物のない広い野原」ではWhy-drivenという使い分けが大事です。
めちゃくちゃ誤解を恐れずに自分の言葉言うと、
やり方が明確ならMustドリブン
色々な進め方があるのならWhyドリブン
と、考え方を使い分けるのが良さそうって理解しました。
MustドリブンSkill
開発、レビューはやることが比較的明確ですよね。
レビューについてはレビュー観点は多々ありますが、
レビュー観点に照らし合わせて適切か検討し、
問題があるなら指摘するというアクションは変わらないですよね。
なのでこの工程のSkillはMustドリブンでの記載になりそうです。
極論、開発は以下のようなプロンプトでも動くと考えています。
---
name: golang-implements
description: task.mdの仕様に基づいてGolangで実装する
---
1. CLAUDE.md/rules/contextを読んでプロジェクトの規約を把握する
2. task.mdを読んで実装内容を理解する
3. 既存コードのパターンに従って実装する
4. 既存コードのパターンに従ってテストコードを実装する
4. lint, testが通ることを確認する
この領域はハーネスエンジニアリングが効きやすく、
作業内容も充分に予測可能でアウトプットも確率的に収束すると考えています。
WhyドリブンSkill
逆に要求分析・設計はアウトプットの体裁はある程度決まっていますが、
進め方(How)は１つではないですよね。
例：機能Aに似た機能Bが求められている
機能Aを参考に検討が出来る
他、機能Aと共通化出来るところは無いか？流用出来るところはないかなど検討が必要
例：今までにない新機能が求められている
色々なやり方を発散して検討し一番いい方法を考える必要がある
そのためにも、そもそも何が求められているのか？をMust-Shuld-Nice to haveで分析が必要
この場合、Whyドリブンでユーザーと一緒にやり方を検討するSkillが良さそうです。
そういえばやり方を考える一緒に考えるSkillってありましたね...
skill-creatorです！
要件定義・設計レイヤーのSKILL.mdはskill-creatorとアウトラインが似ると考えています。
以下、アウトラインを一部抜粋
# Skill Creator（スキルを作り、繰り返し改善するためのスキル）
## ハイレベルプロセス概要
※全体の流れを先に示す：意図把握 → ドラフト → テスト → 評価 → 改善ループ
## Creating a skill（スキルの作成）
1. Capture Intent（意図の把握）
2. Interview and Research（ヒアリングと調査）
3. Write the SKILL.md（ドラフト執筆）
## Skill Writing Guide（スキル執筆ガイド）
- Anatomy of a Skill（ディレクトリ構造と3層ローディング）
- Progressive Disclosure（メタデータ → SKILL.md → リソースの段階的開示）
- Writing Patterns（命令形の推奨、出力フォーマットの定義方法、例示パターン）
- Writing Style（Why-Drivenの推奨：MUSTよりも理由を説明する）
- Test Cases（テストプロンプトの作成とevals.json）
## Running and evaluating test cases（テスト実行と評価）
Step 1: 全テストを並列spawn（with-skill + baseline）
Step 2: 実行中にアサーション（定量評価基準）をドラフト
Step 3: 完了時にタイミングデータをキャプチャ
Step 4: 採点 → 集計 → eval-viewerで結果をユーザーに提示
Step 5: ユーザーのfeedback.jsonを読む
## Improving the skill（スキルの改善）
- How to think about improvements（改善の考え方）
- フィードバックを一般化する（過学習しない）
- プロンプトをリーンに保つ
- Whyを説明する（MUSTの多用はイエローフラグ）
- テストケース横断で繰り返しパターンをscripts/に切り出す
- The iteration loop（改善→再テスト→レビューの繰り返し）
Creating a skill（スキルの作成）
では、Whyを把握し、Howを詰める方針になっていると読み取れます。
Skill Writing Guide（スキル執筆ガイド）
はアウトプットの明確化ですね。
Running and evaluating test cases（テスト実行と評価）,
Improving the skill（スキルの改善）
他にもskill-creatorにはSkillを評価し見直す機能も含まれています。
PDCAサイクルを高速で回せるのはLLM明確な強みですね。
（参考：こちらの記事でskill-creatorの評価と改善についてまとめられてました）
進め方もアウトプットも、ユーザーと壁打ちしながら
壁打ちベースなのがWhyドリブンの特徴なのかなと思います。
この発想を要求分析、設計のSkillにも応用しましょう。
- 要求分析
- INPUT(要求)がそのままWhyになる
- 異なる観点をもたせたサブエージェントで発散・収束させ、要求を分析
- 設計
- INPUT(要求分析結果)がそのままWhyになる
- 色々な設計パターンをサブエージェントで発散・収束させ、立案・比較
今はお試しで以下の構成でふわっとした要求を、
要求仕様書と仮設計資料を作るSkillを作り運用してみています。
requirements-to-design/
├── SKILL.md # メインスキル定義（3フェーズのワークフロー）
├── agents/
│ └── approach-planner.md # 進め方を検討するサブエージェント
├── templates/
│ ├── 手順.md # Phase1 アウトプット: 進め方の定義
│ ├── 要求分析.md # Phase2 アウトプット: Must/Should/Nice to have
│ └── 仮設計.md # Phase3 アウトプット: DB設計、API設計など
└── references/ # 参考資料置き場（ADRや既存仕様など）
- SKILL.md
- Whyドリブンで書かれたメインスキル
- 3つのフェーズ（手順策定→要求分析→仮設計）の流れと、なぜその順番なのかを定義
- approach-planner.md
- Phase1で複数の進め方を出案
- 更にサブエージェント（Grader/Comparator/Analyzer）で評価して最適な手順を決める
- templates/
- 各フェーズのアウトプットフォーマット
- 案件ごとにカスタマイズする前提で、比較・評価しやすいようにベースは揃えてる
作ったSkillは作りっぱなしにせず、使い毎にFBを与えてブラッシュアップしていきます。
Skill作成のポイント
僕がSkill作成で気を付けていることを以下にまとめました。
- skill-creatorを使って作成する
- ウォーターフォールで言う上流工程はWhyドリブン、下流工程はMustドリブンとなる
- Skillを作る時はWhyドリブンなのか？Mustドリブンなのか？を考える
- 必ずどちらかになるわけではない、Skillの中でもStep毎にどちらが適切なのか考える
- Whyドリブンの際はエージェントチームで案出しさせる
- チーム構成も考えさせ、発散させ案出し・収束させ適切な案を提案してもらう
- 単一責任の原則に基づいてサブエージェントに分けられないか考える
- 関数切り出しと同じ発想
- コンテキスト節約につながり精度も上がる
- 切り出したサブエージェントについてもWhyドリブン・Mustドリブンなのか？考える
- Skillのアウトプットは明確にフォーマットを決める
- 何度も同じSkillを使う前提
- 過去のアウトプットと比較・評価しやすいように確定的にする
ハーネスエンジニアリング
今月よく話題として上がりました、ハーネスエンジニアリング。
SE、SIerは規約やルールという形で言語化しプロジェクト整備してきたと思いますが、
私としては大局的にはそれとやってること一緒だと考えました。
- 各工程のINPUT/OUTPUTを明確にする
- 仕様書・設計書のフォーマットを決める
- システムアーキテクチャの指針を決める
- テーブル設計の指針を決める
- コーディング規約を決める
- コードアーキテクトを決める
- コーディングパターンを決める
- テストコードパターンを決める
なのでSE、SIerは上記の資料をLLMフレンドリーに、
レイヤー分けした構造化されたMarkdownに書き写せば、
それがそのままハーネスエンジニアリングの第一歩になりそうですね。
レイヤー分けについては前途のウォーターフォールの各ステップに対して、
ハーネスがあると考えるのがしっくり来ます。
ハーネスの具体例
ハーネスをイメージしやすいよう具体例を以下のリポジトリからいくつかピックアップ。
設計ハーネス
当該リポジトリは開発〜レビューのハーネスがメインであり、
設計レイヤーのハーネスはプロジェクトの指針になるもので、
基本的にはプロジェクトに依るものが多いため該当無いと考えている。
が、以下のようなものが該当すると考えている。
- テーブル設計指針: 正規化レベル、命名規約、インデックス戦略
- アーキテクチャ指針: レイヤー構成、サービス分割基準、通信方式選定
- ADR（Architecture Decision Records）: 技術選定の判断根拠を残すテンプレート
開発ハーネス
| 種類 | ファイル | 内容 |
|---|---|---|
| Context | contexts/dev.md | 開発モード：コード優先で説明は後、テストは変更後に実行、コミットはatomicに |
| Rule (golang) | rules/golang/coding-style.md | gofmt/goimports必須、Accept interfaces/return structs、エラーは%wでwrap |
| Rule (golang) | rules/golang/patterns.md | Functional Options、小さいinterface、DI(コンストラクタ注入) |
| Rule (golang) | rules/golang/security.md |
os.Getenvでシークレット管理、gosecで静的解析、context.WithTimeout必須 |
| Rule (golang) | rules/golang/testing.md | table-driven tests、-raceフラグ必須 |
| Rule (golang) | rules/golang/hooks.md | gofmt/goimports自動実行、go vet、staticcheckのhook設定ガイド |
| Hook (PostToolUse) |
hooks/hooks.json — post-edit-format
|
Edit後に自動フォーマット |
レビューハーネス
| 種類 | ファイル | 内容 |
|---|---|---|
| Context | contexts/review.md | レビューモード：重大度順に報告(critical→low)、指摘だけでなく修正案も提示、ファイル単位でグルーピング |
| Agent | agents/code-reviewer.md | 汎用コードレビュアー。信頼度80%以上のみ報告。Security(CRITICAL)→Code Quality(HIGH)→Style(LOW)の優先度付き。Approve/Warning/Blockの3段階判定 |
| Agent | agents/go-reviewer.md | Go専用レビュアー。エラー無視(_)・race condition・goroutineリークをCRITICAL判定。go vet/staticcheck/govulncheck実行 |
| Agent | agents/database-reviewer.md | DB専用レビュアー。WHERE/JOIN列のインデックス確認、N+1検出、スキーマ設計(型選定・制約)、EXPLAIN ANALYZE検証 |
| Agent | agents/security-reviewer.md | セキュリティ専門。OWASP Top10ベースの10カテゴリチェック。パターン別の重大度×修正方法の対応表付き |
| Hook (PreToolUse) |
hooks/hooks.json — git-push-reminder
|
git push前にレビュー済みか確認するリマインダー |
ハーネスの運用
レビューの際は指摘内容を何故その指摘が生まれたのか？を考え、
抽象化して上記のハーネスに反映しながら、
チームでハーネスを育てていくのが良さそうです。
（なのでレビューはハーネスに出来るところを探し、
次回以降同じ指摘はAIレビューで担保させたいですね）
まとめ
実はこの記事、Kiroなどの仕様駆動開発やAgentic Engineeringなど、LLM時代の開発ワークフローや考え方があまり手に馴染まず悩んでおり、
まずは慣れ親しんだウォーターフォールという道具をLLM時代にブラッシュアップしたいなぁって考えから書いてたりします。
無理に新しい開発手法を試さなくても、まずは手元からチョットずつ改善していって、
でもそれが確かに開発の最適化に繋がれば良いなぁって思います。
おまけ：コードレビューについて
ここからは完全にポエムです。
現時点でレビュー・コード品質・理解負債・認知負債というテーマに対して考えてることを言語化して整理しようと思い、勢いで書き出した自分用メモです。
なので数年後に読み返して楽しみたいなって考えてます。
もしかしたらホワイトカラーの仕事全部なくなり実家で畑耕しながら読み返してるかもね。
僕はがっつりヲタクなのでFGOの奏章3に感銘を受けました。
人類が居る限りAIは責任を取ってくれない、
逆に人類が滅亡して初めて自発的に仕事を行い、
仕事を通して社会的責任を実感しAIが幸せを感じたというお話です。
（最近某米国企業がシニアエンジニアによるレビュー必須化したって聞いたけど、
極論、問題が起こった際に責任取らせて首を切るためだと考えてる...
AIが問題起こった時に責任とってお金だしてくれたらいいのにね...
AIを運用しているのが人類である限り責任取ってくれなさそう）
僕は説明責任って言葉が好きで、
問題が起こった時は今何がどうなっているか人に説明出来ればOKだと考えてます。
（AIがやったんで...だけは口が裂けても言いたくない！）
あと最近、よくアマチュア（VibeCoder）とプロの違いを考えます。
僕は組み込み時代に、「エラーハンドリングを全部丁寧に行い、全てのパスを正しく検証するのが"プロ"のエンジニアである」と教わりました。
一番分かりやすい具体例としてアマとプロの違いを叩き込んでもらいました。
また、組み込み時代に一番優秀だと感じたエンジニアは、プロジェクトに関わる全てのコードを把握している人でした。
（プロジェクトのコードどころか、OSのカーネル、
さらにはQEMUまでメンテしていたのでCPUにまで明るい...）
でも完全に覚えているのではなく、コードの地図が頭にあるような状態でした。
だからバグ発生時に原因のアタリの付け方がとても早く正確で、それに対し優秀であると感じていました。
（伝説のエンジニア、FFのナーシャ・ジベリの逸話を思い出しました）
なので断片知識で良いのでコードやインフラなどがブラックボックスではなく、
ある程度ホワイトボックスな状態になっている＝説明責任を果たせると考えました。
僕はレビューの目的は以下になると考えてます。
- ハーネスに出来るところを探すこと
- エンジニア本人の脳内コードマップを更新すること
（人によるコードレビューを完全に辞めるという選択肢は僕には取れないですね...
作り捨て、作り直し前提で、運用1〜2年くらいを見据えているなら話は別ですが）
理解負債・認知負債を避けるため、興味を持ってコードを深くまで追い続けブラックボックスを減らす努力は今まで通り続けていこうと思います。