はじめに
ADWAYS DEEE 技術改善Div 第一ユニットでシニアアプリケーションエンジニアをやっている市橋です。
今回はOpenSpecのapplyフェーズを自律駆動するスキルを作ってみた話をします。 チームでのClaude Code活用を促進したい方々の参考になれば幸いです。
弊社エンジニアのLLM利用環境
ADWAYS DEEEではClaude Code Maxプランが 全エンジニアに 配布されています。 また、SDD(Spec-Driven Development: 仕様駆動開発)についても検証を進めており、SDDを実践するためのフレームワークであるOpenSpecの導入にチャレンジしています。
弊チームの開発フロー
この環境での開発フローは概ね以下の通りでした。
/opsx:exploreで壁打ち/opsx:ffでchanges作成- 必須ではないが一旦レビュー
/opsx:apply- レビュー
- マージ
課題
Claude CodeやOpenSpec自体はスムーズに受け入れられているのですが、それを本当に使いこなすのは難しいと感じています。 弊チームに限った話ですが、Maxプランを使い切るほどClaude Codeを活用できてはいませんでした。
私見ですが、コーディングエージェントを使いこなしている方々は実装に逐一介入していません。 スキルやサブエージェントをうまく構築し、エージェントに 自律的に レビューと修正をループさせています。 成果物のクオリティをそれなりに高めることで、人間のレビューという遅いフェーズを最小化しています。
この観点で弊チームのフローをみると、 /opsx:apply フェーズに改善の余地があると感じていました。
/opsx:apply を素朴に利用すると、概ね以下のようなことが起きます。
- コミットしない
- 自発的にレビューを受けない
- pushしない
- PRのdescriptionを書かない
これらを自律的に行わせる必要があります。
自律したapplyを行う /opsx-auto-apply を作成
というわけでスキル化してチームに配りました。
スキル名は /opsx-auto-apply です。
このスキルは以下のことをします。
- 必要ならブランチを切る。ブランチ名も勝手に決める
- 以下をレビュー指摘項目が無くなるまでループ
/opsx:apply/opsx:verify- レビュー
- サブエージェントに依頼させる
- 実装内容とOpenSpecのchangesに差分があったら、changesを修正してコミット
- push
- Draft PR作成
- PR description記述
作り方
Claudeに書いてもらい、ちょっとだけ調整しました。
前セクションに書いた内容を伝え、これをやるスキルを作ってとお願いしただけです。
スキルのコード全文
--- name: opsx-auto-apply description: "/opsx:apply以降のワークフロー(実装→検証→レビュー→修正ループ→spec同期→最終検証→コミット&push&PR)をフルオートで実行します。" --- # opsx-auto-apply ## 目的 OpenSpecのapply以降のワークフローを完全自動で実行する。 手動で `/opsx:apply` → `/opsx:verify` → `/review` → 修正ループ → spec同期 → 最終検証 → コミット&push&PR を繰り返す手間を省く。 ## 前提条件 - openspec CLIがインストールされている - 対象のchangeが存在し、tasksアーティファクトが作成済みである - gitリポジトリ内で作業している - デフォルトブランチ(main)上ではなく、作業ブランチが準備されている ## 入力 `$ARGUMENTS` でchange名を指定する。省略時はopenspec listから推定またはユーザーに選択を促す。 ## 実行フロー ### Phase 0: 準備 1. **change名の決定** `$ARGUMENTS` が指定されていればそれを使う。なければ: ```bash openspec list --json ``` で一覧を取得し、1つしかなければ自動選択、複数あればAskUserQuestionで選択を促す。 2. **ブランチ確認** 現在のブランチがデフォルトブランチ(main)でないことを確認する。 mainの場合はエラーとして停止する。 3. **生成されたchangesをコミット & push** openspecが生成したchanges(タスクファイル等)がまだコミットされていない場合、Draft PR作成前にコミットしておく。 - 変更ファイルを個別に `git add` - `git commit` - `git push` 4. **Draft PRをオープン** ```bash gh pr create --draft --title "<change名に基づくタイトル>" --body "WIP: OpenSpec auto-apply in progress" ``` 既にPRが存在する場合はスキップする。PRのURLを記録しておく。 ### Phase 1: 実装(/opsx:apply相当) 1. **openspec instructions applyを実行してコンテキストを取得** ```bash openspec status --change "<name>" --json openspec instructions apply --change "<name>" --json ``` 2. **contextFilesを全て読み込む** 3. **タスクを順次実装する** - 各タスクについてコード変更を実施 - タスク完了時にcheckboxを `[x]` に更新 - 全タスク完了まで継続 4. **コミット & push** - 変更したファイルを個別に `git add` する(`git add -A` 禁止) - `git commit` する - `git push` する ### Phase 2: 初回検証(/opsx:verify相当) 1. **openspec verify手順を実行** - Completeness(タスク完了状況、spec coverage) - Correctness(要件実装マッピング、シナリオカバレッジ) - Coherence(設計準拠、コードパターン一貫性) 2. **CRITICAL issueがあれば修正してPhase 2を再実行** ### Phase 3: コードレビュー 1. **レビューコマンドの選択** 以下の順で判定し、最初に該当するものを使う: - プロジェクトがGoプロジェクト(`.go`ファイルが存在)かつ Go用レビュースキル が利用可能 → Go用レビュースキル を使用 - 上記に該当しない → `/review` を使用 利用可能かどうかは、system-reminderに表示されるavailable skillsの一覧で判断する。 2. **レビューを実行** - 現在のブランチの変更内容(ベースとの差分)を対象にレビューを実施 3. **レビュー結果の評価** - 各指摘事項の重要度を確認 ### Phase 4: レビュー修正ループ レビュー結果にWarningsレベル以上の指摘事項がある場合、以下をループする: 1. **指摘事項を修正する** - CRITICAL → WARNING の順に優先度高く対応 - 修正内容は最小限に留める 2. **修正をコミット & push** - 変更ファイルを個別に `git add` - コミットメッセージは修正内容を反映 - `git push` 3. **再レビュー** - Phase 3で選択したレビューコマンドで再度レビュー 4. **ループ継続判断** 以下を総合的に判断してループを終了する: - Warningsレベル以上の指摘事項がすべて解消された → 終了 - 修正を繰り返しても同じ指摘が残り続ける(修正困難と判断) → 終了し、残課題として記録 - 新たな指摘が発生せず、残りの指摘がSUGGESTIONレベルのみ → 終了 ### Phase 5: Spec同期(/opsx-reverse相当) 1. **コード変更とspecの差分を検知** - `git diff` でapply以降の全変更を確認 - 変更されたコードに関連するopenspec仕様書を特定 2. **差分がある場合、specを更新** - コード実装を正としてspec .mdファイルを更新 - 既存の記述スタイル・形式を維持 - コードは変更しない(.mdファイルのみ更新) 3. **spec更新をコミット & push** ### Phase 6: 最終検証(/opsx:verify相当) 1. **再度openspec verify手順を実行** - spec同期後の状態で3次元検証(Completeness, Correctness, Coherence) 2. **CRITICAL issueがあれば修正 → 再検証(Phase 6をループ)** 3. **最終コミット & push** ### Phase 7: 完了 1. **最終結果レポートを表示** ``` ## Auto-Apply Complete **Change:** <change-name> **PR:** <PR URL> ### Summary - Tasks: X/X complete - Review: Passed (N iterations) - Spec sync: Y files updated - Final verify: All checks passed ### Remaining Notes - <SUGGESTIONレベルの残課題があれば記載> ``` ## ガードレール - `git add -A` や `git add .` は絶対に使用しない - mainブランチでは作業しない - コミット前にプロジェクトのビルド・テストコマンドを実行する - Makefile がある場合: lint/test 系のターゲットを実行(例: `make lint && make test`) - package.json がある場合: `npm test` や `npm run lint` 等を実行 - go.mod がある場合: `go vet ./... && go test ./...` 等を実行 - 上記に該当しない場合: プロジェクトの構成から適切なコマンドを推定する - セキュリティ上の問題(APIキー、パスワード等)を含むファイルをコミットしない - 各フェーズ間でユーザー確認は挟まない(完全フルオート) - エラーが発生した場合は自動リカバリを試み、不可能な場合のみ停止してユーザーに報告 ## コンテキスト $ARGUMENTS
使ってみた結果
これしか使わなくなった
結論、これしか使っていません。
/opsx:apply は使わなくなりました。
前提として、/opsx:explore で入念に壁打ちしていること、すでにリポジトリにコードがあることが必要です。
この前提のもとでは、出来上がるコードのクオリティにほとんど文句がありません。
/opsx-auto-apply を実行して放置している間に、別のタスクを /opsx:explore で固める。
それが終わったらまた /opsx-auto-apply して別のタスクへ、というサイクルで回しています。
今はほぼこれで済んでいます。
チームメンバーが5-hour limit達成
個人レベルの体感がかなり良かったので、チームにも配布してみました。
その結果、チームメンバーもMaxプランの5-hour limitを使い切るようになりました。
利用時間の増加が活用度を直接示すわけではありませんが、 エージェントを使い倒しやすくはなったようです。
考察
OpenSpec がワークフローを定義してくれているから自律させるのも簡単だった
正直なところ、今回作ったようなスキルは、コーディングエージェントを使いこなしている方々は当たり前にやっていることだと思います。
ただ、OpenSpecのワークフローに乗っかったことで展開が簡単になったと感じています。
SDDというものが果たして必要なのか? というのはまだ判断が難しいのですが、 少なくとも、コーディングエージェントを使ったワークフローの標準規約として、OpenSpecは有用そうです。
/opsx:explore が結構いい
エージェントによる開発は事前に方向性を擦り合わせるのが大事です。
このすり合わせを行うツールとして /opsx:explore の体感は良いです。
対話形式で実装方針を詰めていけば、いつの間にか仕様が固まっています。
(繰り返しになりますが)これも、使いこなしている方々は当たり前にやっていることだとは思います。 ただ、このスキルを使えば誰でもある程度のクオリティでできるのが魅力的だと思っています。
/opsx-auto-apply も、/opsx:explore を通して作られる changes のクオリティが高いから使い物になっていると感じています。
今後の展望
今回は /opsx:apply を自律的に動作させることに成功しました。
この自律的動作の範囲をさらに広げたいと考えています。
/opsx:ff以降を自動化してしまう- exploreでちゃんと会話しておけば、changesも十分なクオリティになる可能性がある
- 結局実装後にchangesは修正されるので、事前に詰めすぎる必要はないと考えている
- ただし、changesを確認してすれ違いに気づく機会がなくなるという課題がある
/opsx:exploreを不要にし、/opsx:newで済ます- コンテキストが潤沢なら、そもそも
/opsx:exploreは不要かもしれない - ある程度開発が進んだ後なら、
/opsx:newでも十分なchangesが出てくるようだ - ただし、ここでの方向性調整がエージェントの暴走を防いでいる側面もあり、判断が難しい
- コンテキストが潤沢なら、そもそも
まとめ
- 実装を自律化するスキルを作った
- 自分だけではなくチームで活用できるものになった
- OpenSpecは少なくともワークフロー規約として有効
- コンテキストが潤沢ならもっと自律化できるかも