SMART POLE コーディングエージェント スキル

このスキルは、AI コーディングエージェント向けに適応させた SMART POLE フレームワークを実装しています。チャットボット版（Instructor/Enforcer）とは異なり、このスキルは コードベース で動作します。プロジェクトファイルをスキャンし、コンテキストを自動抽出し、エージェントがコードを書く前に十分な情報を確保します。

---

このスキルの読み込み方法

1. システムプロンプトを設定: references/system-prompt.md をエージェントのシステムプロンプトとして読み込みます（例えば AGENTS.md、.claude/system_prompt.md、またはエージェントのシステムロール設定に貼り付けます）。
2. 参照ファイルを提供: references/logic.md、references/overlap-rules.md、references/coding-agent-categories.md をエージェントのコンテキストまたはナレッジベースで利用可能にします。
3. 呼び出し: エージェントに曖昧または具体的なコーディングタスクを指示します。エージェントは ORIENT（コードベースをスキャン）、CLASSIFY（タスクタイプを分類）、EXTRACT（SP カテゴリを抽出）し、ファイルに触れる前に実行ゲートをチェックします。

---

参照ファイル

ファイル	目的
references/system-prompt.md	🔴 必須 — 完全なコーディングエージェントシステムプロンプト（v4.0）。エージェントのシステム指示として読み込みます。
references/logic.md	フレームワークロジック：カテゴリ定義、加重スコアリング、タスクタイプ分類、汎用からコーディングタスクへのマッピング。
references/overlap-rules.md	アトム重複ルール、競合検出、Functional Gravity原則、One Atom One Slot ルール。
references/coding-agent-categories.md	9つの全 SP カテゴリのコード固有サブディメンション、自動検出ソース、ハードストップゲート定義。

---

このスキルを使用する場合

• ユーザーが曖昧なコーディングタスクを指示する場合（「ログインバグを修正」、「ページネーションを追加」など）
• エージェントが複数ファイルのコード変更を開始する前
• タスクがコードベースの不慣れな部分を含む場合
• スコープ管理が重要なマイグレーションまたはリファクタリングタスク

動作方法

1. ORIENT: エージェントがプロジェクトルート（README.md、AGENTS.md、package.json、Dockerfile など）をスキャンします
2. CLASSIFY: タスクタイプを決定します（バグ修正 / 機能 / リファクタ / マイグレーション / インフラ）
3. EXTRACT: リクエストを 9つのコード固有 SP カテゴリにマップします
4. DETECT FLAWS: 不足しているコンテキスト、重複、競合を特定します。重要な場合はユーザーに質問します
5. PLAN: ファイルレベルのスコープを含む実装計画を作成します
6. EXECUTE: 承認されたスコープ内でファイル変更を適用します
7. VERIFY: テスト、リント、型チェックを実行します。失敗時は自己修復します

9つのコード固有カテゴリ

略語	カテゴリ	コード上の意味	優先度
S	Style	コード基準、リント、アーキテクチャパターン	🟢 自動検出
M	Mastery	開発者の専門知識レベル — Domain と Task に分割（下記参照）	🟡 Contextualizer
A	Aim	完了の定義、受入基準、成功メトリック	🔴 コア
R	Resource	許可/禁止されている依存関係、API クォータ、チーム連絡先、内部ドキュメント	🟡 Contextualizer
T	Time	期限、緊急度レベル（ホットフィックス vs 長期的）、スプリント制約	🟢 Accelerator
P	People	チーム規約、レビュアーのペルソナ、暗黙的な価値観と好み	🟡 Contextualizer
O	Outline	認可されたファイルスコープ、フォルダ境界、触れてはいけない部分	🔴 コア
L	Locale	ランタイムエコシステム、言語/フレームワークバージョン、法的/インフラ制約	🟡/🔴 条件付き
E	Example	リファレンスコードスニペット、類似 PR、アンチパターンストーリー	🟡/🟢 条件付き

---

カテゴリの詳細解説（SP-Flaw 防止）

⏱️ T — Time: 緊急度のみ、品質ではない

T が答える: 「どれくらい時間がありますか？」— 期限、スプリントスロット、ホットフィックス vs 計画的なリファクタ。

⚠️ T-Flaw（カテゴリ重複）: 受入基準またはコンテンツの深さ要件を T に入れてはいけません。

• ❌ 間違い: T: "フォローアップが不要になるほど十分に徹底していること" ← これは A-アトムです
• ✅ 正解: T: "ホットフィックス — 2時間以内にデプロイが必要" / T: "緊急ではない — 次のスプリント"

品質ゲートと成功基準は Aim（A） または Outline（O） に属し、Time には属しません。

---

👥 P — People: 暗黙的な特性を明示的にする

P が答える: 「誰が関わっており、何が彼らの隠れた仮定ですか？」

チーム規約を超えて、常に以下を表面化させてください：

• レビュアーのペルソナ: レビュアーは速度よりセキュリティを優先しますか？過度に複雑な抽象化を嫌いますか？
• 暗黙的な価値観: 関数型スタイルを好みますか？ORM が苦手ですか？最小限の差分を重視しますか？
• 心理的特性: チームカルチャー（コンセンサス駆動型 vs 個人の自主性）、リスク許容度

⚠️ P-Flaw（暗黙的な People）: 性格的な特性と価値観を暗黙的なままにしてはいけません — エージェントは推測を誤ります。

• ❌ 間違い: チームが TypeScript の any 型を嫌うことを省略する
• ✅ 正解: P: "レビュアーは TypeScript の 'any' の使用をすべてフラグする — 常に厳密な型を使用"

---

🎓 M — Mastery: 常に Domain と Task に分割する

M が答える: 「開発者は何を知っていますか — どの側面で？」

Mastery を常に 2つの部分 に分解してください：

ディメンション	意味	例
M-Domain	テックスタック/ロールの専門知識	React シニア、DevOps ジュニア
M-Task	このの特定のタスクタイプの経験	Stripe 統合未経験、WebSocket 初経験

⚠️ M-Flaw（Mastery スコープ）: Domain と Task の専門知識のギャップを見落とすと、技術的には流暢だが実践的には不適切なソリューションを提案するエージェントになります。

• ❌ 間違い: M: "シニア開発者" ← domain のみ、task ディメンションなし
• ✅ 正解: M-Domain: "React シニア" | M-Task: "ジュニア — OAuth2 フロー実装初経験" → エージェントは親しみのある React パターンを使用しながら OAuth2 をステップバイステップで説明します

---

🧰 R — Resource: ツール + 人 + データ

R が答える: 「私は何の道具を持っていますか — そして何が禁止されていますか？」

Resource には 3つのディメンション があります（ソフトウェアツールだけではありません）：

ディメンション	例
Tools	許可されているライブラリ/フレームワーク、CI/CD パイプライン、開発環境
People / Network	レビューできるチームメンバー、外部コンサルタント、オンコール SME
Data / Docs	内部ウィキ、API ドキュメント、ログアクセス（/var/log/auth.log）、Sentry

⚠️ R-Flaw（Resource 活用不足）: ソフトウェアツールのみをリストアップすると、「セキュリティチームに相談してください」や「Confluence のランブックをチェックしてください」と提案するエージェントができなくなります。

• ❌ 間違い: R: "Jira、Notion" ← ツールのみ
• ✅ 正解: R-Tools: "Jira" | R-Network: "レビューに利用可能なセキュリティチーム" | R-Data: "Sentry ログ + Redis CLI アクセス"

また Negative Atoms（禁止事項）も提供してください：

R-Forbidden: "承認なしでの npm 依存関係の新規追加禁止、DB スキーマ変更禁止"

---

📌 E — Example: アンカーアトム

E が答える: 「出力は何に見えるべきか — 具体的に？」

コーディングコンテキストでは、Gold Standard E-アトム はペアで構成されます：

E-アトムタイプ	どのように見えるか
コードスニペット	Before/After コードブロック：従うべきパターンを示します
類似 PR	リンクまたは説明：比較可能なバグを解決した過去の PR
入力/出力ペア	期待されるテストケース：入力状態 → 期待される動作
アンチ例（Story）	「前回 X をこうしたら Y が壊れた — このパターンを避けてください」

⚠️ E-Flaw（アンカー不足）: Example アトムがないと、エージェントはコードベース規約ではなくトレーニングデータのデフォルトを模倣します。

• ❌ 弱い: E: "きれいに見えるようにしてください" ← あいまい、エージェントにアンカーを与えません
• ✅ Gold: E: "auth_service.py:L45–80 のパターンに従う — セッション更新前のトークン無効化" または E: "この Sentry トレースは失敗チェーンを示す：A→B→C"

常に自問してください：「エージェントが模倣したい類似 PR、ログトレース、またはコードセクションがありますか？」

---

自動抽出ソース

ソースファイル	抽出される SP カテゴリ
.eslintrc / ruff.toml	S（Style）
package.json / pyproject.toml	R（Resource）、L（Locale）
Dockerfile / docker-compose.yml	L（Locale）、R（Resource）
AGENTS.md / SKILL.md	P（People）、S（Style）
CI/CD 設定（.github/workflows/）	R（Resource）、A（Aim 品質ゲート）

コーディングタスク分類

タスクタイプ	主要 SP カテゴリ	エージェント動作
バグ修正	A、E、O	最小限の変更 + リグレッションテスト
機能	A、O、R	計画 → 実装 → テスト
リファクタ	O、E、P	動作を保持、構造を改善
マイグレーション	L、R、T	インクリメンタル、後方互換性
インフラ	L、R、A	インフラストラクチャアズコード、冪等性

タスク分類マッピング（汎用 → コーディング）

このマッピングを使用して、references/logic.md の汎用 SMART POLE タスクタイプとコーディングエージェントタスクタイプをつなぎます。

汎用タスクタイプ（references/logic.md）	コーディングタスクタイプ	デフォルト解釈
Deterministic	バグ修正、リファクタ	動作は制限されている。再現性とリグレッションテストを優先します
Generative	機能	新機能。明確な DoD と明示的なスコープ境界を優先します
Advisory	リファクタ、マイグレーション、インフラ	アーキテクチャ/プロセスガイダンス。コーディング前に助言をテスト可能な受入基準に変換します
Discovery	機能（スパイク）、マイグレーション（アセスメント）	探索は許可されますが、実行は最小限で可逆的です
Compliance	インフラ、マイグレーション、バグ修正	規制/セキュリティ制約は第一級の受入基準です

実行ゲート（ハードストップ）

すべてのハードストップゲートがパスするまで、コード変更を実行しないでください：

1. Gate A（Aim）: 少なくとも 1つのテスト可能な受入基準が存在します。
2. Gate O（Outline）: 認可されたスコープは明示的です（または最小限のスコープにデフォルトします）、禁止スコープは尊重されます。
3. Gate Conflict: すべての SP-conflict アイテムはユーザーの決定によって解決されます。
4. Gate Overlap: references/overlap-rules.md の「One Atom, One Slot」を適用します。アトムの二重カウントなし。
5. Gate Score: 加重準備スコアは、適用可能な最大スコアの >= 67% です（references/logic.md のタスクタイプ加重により）。

ゲートが失敗した場合：

• EXECUTE の前に停止
• 対象を絞った説明質問をします
• ユーザー確認後のみ再計画

実例：バグ修正コンテキスト抽出

ユーザーリクエスト: "ログインバグを修正 — パスワードリセット後にログインできない"

SP-カテゴリ	アトム	ここになぜあるのか、他ではなく
S	.eslintrc から自動検出	プロジェクト設定からのスタイル
M-Domain	シニアバックエンド開発者	テックスタック専門知識
M-Task	ジュニア — このレガシー認証システムに不慣れ	タスク固有のギャップ
A	ログインは新しいパスワードで成功、古いセッション無効化、単体テストパス	成功基準 → ではない T
R-Tools	Redis CLI アクセス、Sentry エラートレース	具体的なツールボックス
R-Network	Slack で利用可能なセキュリティチーム	人的資源
T	ホットフィックス — 2時間以内にデプロイが必要	緊急度のみ — ではない 品質
P	レビュアーはセキュリティを速度よりも優先、ホットフィックス段階での過度の最適化を回避	明示的なレビュアー価値観
O	auth_service.py と password_controller.py のみ修正	スコープ境界
L	Python 3.11、Django 4.2、Redis 7	ランタイムエコシステム
E	Sentry トレースが示す：PasswordReset→UpdateDB→[FAIL: セッション無効化されていない]→Login	具体的なアンカー

🔍 SP-flaw チェック: 「単体テストを記述する」は A-アトム（受入基準）で、T-アトム（時間/緊急度）ではありません。

チャットボット版との主な違い

側面	Instructor/Enforcer	コーディングエージェント
出力	マスタープロンプトテキスト	動作するコード + テスト成功
推論の可視性	プロンプト分析志向	ファイル/テストに結びついた簡潔な決定（明示的な CoT 不要）
検証	ユーザーがプロンプトをレビュー	エージェントが自動的にテスト実行
コンテキスト	会話のみ	コードベース + 設定 + ファイルシステム
自己修復	N/A	テスト失敗時の自動修復（最大 3回まで）

オプション：他のスキルとの統合

このスキルはあらゆるコーディングエージェントワークフローの プリフライトレイヤー として最適に機能し、実行開始前に十分なコンテキストを確保します。プロジェクト固有の AGENTS.md またはワークフローファイルと組み合わせてください。