audit-clerk-skill

Clerk CLI スキルの監査

このリポジトリの skills/clerk-cli/ を実際の Clerk CLI ソースと照合し、スキルの記述にずれがある箇所について、正確な編集案を提示してください。CLI を正とし、スキルはそれに追従するメンテナー向けドキュメントです。

このタスクでは、手早く grep するのではなく、コマンドを完全に一覧化する必要があります。まずソースのモデルを作成し、その後、スキルの現在の記述と比較してください。

入力

• CLI の正となるソース：packages/cli-core/src/commands/**、および packages/cli-core/src/cli.ts、cli-program.ts、mode.ts と、参照されている packages/cli-core/src/lib/ 内のファイルを含む clerk/cli のチェックアウト。
• 対象スキル：skills/clerk-cli/SKILL.md および skills/clerk-cli/references/*.md。

ソースチェックアウトの解決

CLI ソースのチェックアウトは、次の順序で解決してください。

1. --source <path> が指定されている場合は、そのパスを使用します。このパスには packages/cli-core/src/commands/ が含まれている必要があります。
2. 現在のリポジトリに packages/cli-core/src/commands/ が含まれている場合は、現在のリポジトリのルートを使用します。
3. CLERK_CLI_REPO が設定されている場合は、そのパスを使用します。機密性のあるパス断片を含む場合、変数の値を出力しないでください。
4. Conductor では、../cli/*/packages/cli-core/src/commands/ に一致する兄弟ワークスペースを正確に 1 つ探します。一致するものが複数ある場合は、どれを使用するかユーザーに確認してください。
5. チェックアウトがなく、タスクでネットワークアクセスが許容される場合は、公開 CLI リポジトリを .context/clerk-cli-source にクローンします。

mkdir -p .context
cd .context
git clone --depth 1 https://github.com/clerk/cli.git clerk-cli-source

いずれの方法でも解決できない場合は、CLI ソースのパスをユーザーに尋ねてください。インストール済みの clerk バイナリだけを基に監査してはいけません。バイナリは古い可能性があり、ソースレベルのすべての分岐を確認できないためです。

ワークフロー

1. CLI の一覧化

packages/cli-core/src/commands/ を調べ、構造化された一覧を作成します。トップレベルのコマンドとサブコマンドごとに、次の情報を記録してください。

• clerk config patch や clerk api ls のような完全なコマンドパス。
• ソース内のコマンド説明またはヘルプ文字列に基づく用途。
• 短縮形、型、デフォルト値、破壊的な動作を含むフラグ。
• コマンドが上書きするデフォルト以外の終了コード。
• isAgentMode()、CLERK_MODE、TTY の検出、または関連ヘルパーによって制御されるエージェントモードの分岐。
• コマンドがリモート状態を変更するかどうか、および --dry-run、--yes、本番環境を対象とする際のガイダンスが必要かどうか。

packages/cli-core/src/commands/<name>/README.md は補足情報としてのみ参照してください。モックまたはスタブのコマンドを明らかにするため、および references/recipes.md に記載された API エンドポイントの説明を照合するために使用します。コマンドの README をこのリポジトリにコピーする提案はしないでください。内部実装の詳細が含まれており、スキルが肥大化するためです。

横断的な動作についても記録してください。

• ロックファイルからパッケージランナーへのマッピングを含む、ランナーの優先順位ロジック。
• 認証、キー解決、--app、--instance による対象指定。
• doctor のチェック項目と --json の出力形式。
• プロンプト、JSON のデフォルト、ブラウザーの起動、OAuth コールバック、デプロイの引き継ぎ、サンドボックスに関する警告でのエージェントモードの動作。
• スキルに記載がある場合は、clerk init --prompt または同等の引き継ぎ動作。

バイナリを実行するよりも、ソースを読むことを優先してください。実行時の動作が明確でない場合は、補足根拠として packages/cli-core/src/**/*.test.ts または packages/cli-core/src/test/ のテストを参照してください。

2. スキルの記述を抽出

skills/clerk-cli/SKILL.md と skills/clerk-cli/references/ 内の各ファイルを読み、具体的な記述をすべて抽出してください。

• 中核となるコマンド表および呼び出し方法の説明に記載されたコマンド。
• 説明文、表、例で言及されているフラグ。
• エージェントモードの動作に関する箇条書き。
• 終了コード、エラー形式、JSON 出力に関する記述。
• SKILL.md と references/*.md の相互参照。

3. スキルとソースの差分を確認する

次の4つの区分で、構造化された差分を作成します。

1. スキルに記載がない：ソースに存在するものの、スキルのどこにも記載されていないコマンド、サブコマンド、フラグ、動作。
2. スキルの情報が古い：名前が変更されたフラグ、変更された既定値、削除されたコマンド、変更された終了コード、再構成されたエージェントモードの分岐など、ソースと一致しなくなったスキルの記述。
3. スキルの説明が不十分：コマンドには触れているものの、実際の複雑さや注意すべき落とし穴が十分に説明されていない記述。
4. 説明過剰：clerk <cmd> --help、生成された例、または参照先のファイルで確認できる詳細を、スキルに記載しているもの。

区分1〜3では、ソースファイルと行番号、および対象となるスキル内の箇所を両方示してください。

4. 配置を決める

保守上の価値に基づいて、変更の配置先を決めます。

• コアループ、メンタルモデル、安全性に関する内容は SKILL.md に残します。
• コマンドごとのフラグ詳細、レシピ、エッジケースは references/recipes.md または新しいリファレンスファイルに配置します。
• エージェントモードの分岐は references/agent-mode.md に配置し、SKILL.md には簡潔な概要のみを記載します。
• 認証、キーの解決、対象の指定は references/auth.md に配置します。

生成されたヘルプを重複して記載するより、clerk <command> --help を優先してください。破壊的な動作を伴うフラグ、隠れた相互作用があるフラグ、またはエージェントモードで挙動が異なるフラグは、スキルで説明する価値があります。自己説明的なフラグは通常、本文から削除し、--help に委ねます。

ドリフトのリスクを減らせるなら、スキルの縮小も有効な提案です。目標は、スキルを大きくすることではなく、正確で長期にわたり保守しやすいものにすることです。

5. 編集案を提示する

レビュー可能な提案を作成します。各変更には以下を含めてください。

• skills/clerk-cli/SKILL.md や skills/clerk-cli/references/agent-mode.md などのパス。
• 重要度：drift、gap、polish のいずれか。
• packages/cli-core/src/commands/<cmd>/<file>.ts:<line> のようなソースの引用を添えた理由。
• このリポジトリ内の対象箇所。
• 実用的な場合は unified diff、そうでない場合は簡潔な変更前・変更後のブロック。

提案は対象ファイルごとにまとめてください。近くにあるという理由だけで、正確な箇所まで書き換えないでください。

6. 適用するか、レビューに回す

既定の動作では、提案を提示して終了します。

--apply が指定された場合は、drift と gap の編集を直接適用し、polish の提案はレビュー用に一覧表示します。編集の適用後、このリポジトリで利用可能な整形コマンドまたは検証コマンドを実行します。フォーマッターがない場合は、軽量なチェックで Markdown と JSON の構造を検証します。

ガードレール

• フラグを捏造しないでください。テストには現れるものの、コマンドパーサーには存在しないフラグは、人による確認が必要な項目として記載してください。
• 既存の clerk-cli スキルの簡潔な三人称の文体を維持してください。
• 提案や編集では em dash を使用しないでください。
• skills/clerk-cli/SKILL.md は、500行前後のガイダンスに収めてください。メインのスキルが肥大化する場合は、詳細を references/ に移してください。
• インストール済みの clerk バイナリを、ソースより権威ある情報源として扱わないでください。ソースとテストを確認しても曖昧さが残る場合に限り、生成された表示内容の確認に --help を使ってください。
• シークレットをコミットしたり、出力したりしないでください。環境変数に関するガイダンスを確認する場合は、リポジトリの「1Password を使用すること」および「シークレットを平文で保存しないこと」というルールを維持してください。

出力形式

提案は次の形式で返してください。

# clerk-cli skill audit - <YYYY-MM-DD>

## Summary
<counts per bucket, plus the largest drift>

## skills/clerk-cli/SKILL.md
### <section name>
- [drift|gap|polish] <one-line description>
  - source: packages/cli-core/src/commands/<...>:<line>
  - target: skills/clerk-cli/SKILL.md:<line>
  - change: <diff or concise before/after>

## skills/clerk-cli/references/<file>.md
...

## New files
...

## Open questions
...

保守担当者が各項目を承認、却下、または適用しやすいよう、読みやすくまとめてください。