pua-loop

pua-loop スキルの概要

pua-loop は何のためのスキルか

pua-loop は、長くて段階の多い実装タスク向けのループ実行スキルです。途中でいちいち質問を挟まず、エージェントに反復作業を続けてほしい場面に向いています。自律的な再試行ループと、リポジトリ内の pua:pua の振る舞いルールを組み合わせることで、作業確認、検証、修正、再実行を繰り返し、完了と判断できるまで進み続けます。

pua-loop が特に向いているケース

pua-loop skill の主な読者は、ローカルで結果を検証できるコーディング作業や運用タスクに取り組む人です。たとえば、バグ修正、リファクタリング、機能の仕上げ、テスト修復、繰り返し発生するクリーンアップ作業などです。とくに pua-loop for Workflow Automation は、多少の不完全な前提を飲み込んでも、途中で止まって確認されるコストのほうが高い場面で有効です。

実際に解決したい仕事

多くのユーザーが本当に求めているのは、「うまいプロンプト」ではありません。範囲の決まった作業をまとめて渡し、数分おきにエージェントを見張らなくて済む状態です。pua-loop は、その引き継ぎを前提に設計されています。中核となる価値は、自律反復にあります。現状を確認し、変更を加え、検証を走らせ、失敗原因を見極め、次の修正に進む、という流れを途切れさせません。

pua-loop が他と違う点

pua-loop の最大の違いは、粘り強さを前提にした設計思想です。ループモード中はユーザーに質問しないことが明示されており、諦める前に選べる手段を尽くすことが期待されています。さらに、ローカルファイルにループ状態を保持するため、単発のプロンプトよりもコンテキスト圧縮の影響を受けにくく、同じ動作方針を維持しやすいのも特徴です。

導入前に知っておきたい注意点

これは汎用的な「より賢くコーディングする」スキルではありません。pua-loop が最も力を発揮するのは、成功条件が明確で、実行可能なチェック手段があるタスクです。要件が曖昧だったり、プロダクト判断を頻繁に挟む必要があったり、外部承認に依存したりする作業では、通常の対話型プロンプトのほうが安全なことが多いです。

pua-loop スキルの使い方

使い始める前に導入前提を確認する

提示されているリポジトリ抜粋には SKILL.md しかなく、このスキルは tanweai/pua リポジトリ全体の支援を前提にしています。そこにはセットアップ用スクリプトのパスや、pua:pua コアスキルの挙動も含まれます。本格的に使う前に、リポジトリのルートを確認し、参照されているループ用スクリプトとコアスキルが、自分の導入環境に実際に存在するかを確かめてください。

pua-loop はどう起動するか

ドキュメント上の起動方法は /pua:pua-loop "task description" です。説明文には loop mode、自动循环、一直跑 のような自然言語トリガーもありますが、pua-loop usage を確実に呼び出すなら、曖昧さの少ないスラッシュコマンドが最も安全です。

起動後に何が起きるか

起動すると、このスキルはセットアップコマンドを実行し、.claude/pua-loop.local.md を生成します。このファイルにはタスク内容とループ用プロトコルが保存されます。その後、stop hook がそのファイルを使って、各イテレーションごとにエージェントへ指示を再投入します。実運用では、毎回ワークフローを説明し直さなくても、同じタスク進行パターンを継続しやすくなる、という理解で問題ありません。

pua-loop をうまく機能させる入力

pua-loop を使うなら、最初に次の4点を渡すのが基本です。

1. タスクの到達結果
2. 対象となるリポジトリまたはフォルダ範囲
3. 検証コマンド
4. 絶対に守る制約

弱い入力の例:

• “Fix the app.”

強い入力の例:

• “Use pua-loop to fix the failing login flow in apps/web. Success means pnpm test --filter web passes and the OAuth callback no longer throws a 500. Do not change the database schema. Prefer the smallest safe fix.”

後者のように指定すると、どこを触るべきか、どう検証するか、何を触ってはいけないかが明確になるため、無駄な反復をかなり減らせます。

曖昧な依頼を完成度の高い pua-loop プロンプトにする

実用的な pua-loop guide の型は次のとおりです。

• Task: 何を作るか、何を直すか
• Scope: ファイル、パッケージ、サービスの境界
• Verification: tests、lint、build、smoke check
• Constraints: スキーマ変更なし、新規依存追加なし、API 互換性維持
• Priority: 最速で安全な修正を優先するか、深めのリファクタを許容するか

例:

• /pua:pua-loop "Resolve TypeScript errors in packages/api only. Run pnpm --filter api build after each meaningful fix. Do not modify public endpoint contracts. Stop only when build passes and no new lint errors are introduced."

先に読むべきリポジトリ内ファイル

まず確認したいのは次です。

• skills/pua-loop/SKILL.md

そのうえで、親リポジトリ側で次も確認してください。

• pua:pua コアスキル定義
• scripts/setup-pua-loop.sh のようなスクリプト
• hook の説明や Claude プラグインの設定ファイル

この順番が重要です。pua-loop install を判断するうえで本当に大事なのは説明文そのものよりも、自分のローカル環境がセットアップスクリプトと stop-hook ベースのループを実際に支えられるかどうかだからです。

各イテレーションで pua-loop が実際にしていること

このスキルの中核ルールはシンプルです。

• pua:pua の振る舞いを読み込む
• ユーザーに質問しない
• “cannot solve” のように途中で打ち切らない
• 変更のたびに検証し、問題を見つけ、修正し、再度検証する

そのため pua-loop は、通常のアシスタントとのやり取りというより、自律的な修復サイクルに近い動きをします。

通常のプロンプトではなく pua-loop を使うべき場面

次の条件なら pua-loop を選ぶ価値があります。

• 成功を自動で確認できる
• 修正と検証を何度か回す前提がある
• 途中の割り込みを減らしたい
• リポジトリ内に実行可能なコマンドがある

逆に、次の条件なら見送るほうが無難です。

• 各ステップでプロダクト判断が必要
• テストや実行時チェックにエージェントがアクセスできない
• 誤った前提のコストが大きい

初回利用時の実践的な進め方

最初の一回は、次の進め方が堅実です。

1. 大規模な書き換えではなく、範囲の限定された1件から始める
2. 検証コマンドを正確に含める
3. 対象範囲を1つのパッケージや機能に絞る
4. ループを回す
5. 最終的な変更をレビューしてから、適用範囲を広げる

これで、要件が薄いまま自信過剰な自律修正が走る、という導入時の代表的なリスクを抑えられます。

停止方法と安全上の境界

このスキルには、停止手段として /cancel-pua-loop と .claude/pua-loop.local.md の削除という2つの経路が記載されています。自律反復を有効にする前に、この2つを運用上の前提知識として押さえておくべきです。もし自分の環境でそのファイルを簡単に確認・削除できないなら、pua-loop skill はその環境にあまり向いていない可能性があります。

pua-loop スキル FAQ

pua-loop は初心者にも向いているか

はい。ただし、対象タスクがきちんと絞られている場合に限ります。初心者にとって自動化の恩恵は大きい一方で、指示が曖昧になりやすい傾向もあります。初めてなら、自由度の高いアーキテクチャ相談ではなく、失敗しているテストや build エラーの修正から始めるのが安全です。

pua-loop は通常のプロンプトを置き換えるか

いいえ。pua-loop が得意なのは実行ループであって、共同で方向性を探る対話ではありません。まだ方針選定中だったり、選択肢比較や要件整理が必要だったりするなら、まず通常のプロンプトを使い、計画が固まってから pua-loop に切り替えるのが適切です。

pua-loop install がうまくいかない最大の要因は何か

多くの場合は環境不一致です。このスキルはセットアップスクリプトと、stop hook によるループ継続を前提にしています。ローカルの Claude / plugin 環境にその仕組みがなければ、markdown だけでは意図した自律動作は再現できません。

pua-loop はテストなしでも使えるか

使えなくはありませんが、品質は下がります。テスト、build コマンド、smoke check がないと、各イテレーションで改善したかどうかを判断するためのシグナルが弱くなります。その状態では pua-loop usage は推測頼みになりやすく、信頼性も落ちます。

“keep trying” と言うだけの場合と pua-loop は何が違うのか

単純なプロンプトでも粘り強さを求めることはできますが、pua-loop には明確な運用パターンがあります。ローカルファイルによる状態保持、反復的な検証、明示的な no-question モード、完了シグナルの運用です。導入する価値があるのは、まさにこの構造のためです。

pua-loop for Workflow Automation を使うべきでない場面は

ワークフローが人間の承認ゲート、外部認証情報、曖昧な業務ルール、あるいは「完了」の定義が主観的な作業に依存するなら、pua-loop for Workflow Automation は避けるべきです。自律ループが役立つのは、完了条件を検証できる場合に限られます。

pua-loop スキルを改善する方法

pua-loop に測定可能なゴールを与える

pua-loop の結果を最も手早く改善する方法は、完了条件を機械的に判定できる形で定義することです。“Make it work” では弱すぎます。“All auth tests pass, build succeeds, and /login/callback returns 200” なら強い指示になります。pua-loop は反復を前提にしているため、自分で検証できる到達点が必要です。

スコープを絞って自律判断の事故を減らす

pua-loop は追質問を避ける設計なので、広すぎるタスクは不要なリスクを生みます。“refactor payments” ではなく、“fix duplicate retry handling in services/payments/retry.ts without changing webhook payloads” のように指定してください。スコープを狭めるほど、速度も安全性も上がります。

破壊的な修正を防ぐ制約を先に渡す

よい制約は、単なるおまけではありません。ループが間違った問題を解いてしまうのを防ぐ役割があります。有効な例としては次が挙げられます。

• 依存関係を追加しない
• スキーマを変更しない
• API レスポンスの後方互換性を保つ
• 全面書き換えより最小パッチを優先する

こうした指定は、pua-loop の出力品質を直接引き上げます。

使える中で最も強い検証コマンドを選ぶ

チェック手段が複数あるなら、ノイズの多いものではなく、その問題に最も効くものを選ぶべきです。UI バグなら、モノレポ全体を走らせるより対象を絞ったテストスイートのほうが有効です。型の問題なら、広範な lint より影響パッケージに対する tsc のほうが適切な場合もあります。検証が良いほど、ループ判断も良くなります。

コンテキスト不足による失敗パターンを見込む

よくある pua-loop の失敗パターンは、ある程度予測できます。

• タスク説明が曖昧
• リポジトリのパスやモジュール範囲がない
• 検証コマンドがない
• 非技術的な要件が隠れている
• 関係ないパッケージで自律変更が走る

この多くは、内容を変えずに再実行するより、最初のプロンプトを改善することで解消できます。

初回実行のあとに、より鋭い指示で回し直す

最初の pua-loop が惜しいところまで行っても、単に “try again” と言うだけでは不十分です。不足していたシグナルを追加してください。

• 何がまだ失敗しているか
• どのファイルの触り方が誤っていたか
• どのトレードオフを優先すべきか
• どの検証結果を最重視するか

そうすることで、2回目は手当たり次第の再ループではなく、方向づけされた修正になります。

コア依存を読んで信頼性を見極める

pua-loop は pua:pua の挙動を継承するため、導入前には上級ユーザーほどこのコアスキルを確認すべきです。その判断ルールや圧の強いスタイルが合わないなら、このループ用ラッパー自体が向いていない可能性があります。情報を踏まえて pua-loop install を判断するうえで、これは最重要クラスのリポジトリ確認ポイントです。

まずは限定的な自動化から始め、徐々に広げる

多くのチームにとって、最適な pua-loop guide は段階導入です。最初はチェックが明確な修復作業に使い、次に小さな機能仕上げへ広げ、それから大きめの自動化フローに進むのが無難です。この順序なら、ループの振る舞いが自分たちのリポジトリやリスク許容度に本当に合うかを見極めながら導入できます。