ds-ai-coding-skills

関連リンク

セットアップ

前提条件

• Python 3.11
• uv がインストール済みであること

インストール

uv sync

主要コマンド

uv sync                                              # 依存関係のインストール・同期
uv run pytest                                         # テスト実行
uv run ruff check .                                   # リント
uv run ruff format .                                  # フォーマット
uv run mypy src                                       # 型チェック
uv run python scripts/check_no_raw_data_commit.py     # rawデータのコミットチェック
uv run python scripts/check_no_sensitive_patterns.py   # 秘密情報パターンの検出
uv run python scripts/validate_agent_docs.py           # エージェント文書の検証
bash scripts/run_quality_checks.sh                     # 全品質チェック一括実行

ディレクトリ構成

.
├── AGENTS.md                          # Copilot / Codex 用ルーター（CLAUDE.md と同内容）
├── CLAUDE.md                          # Claude Code 用ルーター（ハードルール・スキルルーティング）
├── .github/
│   ├── workflows/ci.yml               # GitHub Actions CI
│   ├── instructions/                  # パス別補助指示（Copilot の applyTo 用）
│   └── prompts/                       # 再利用プロンプト（Copilot）
├── .claude/
│   └── skills/                        # 作業別スキルの唯一の置き場（3ツール共通。旧スラッシュコマンドを含む）
│                                      #   *-diagnostics は2段構成: ルーター SKILL.md + references/<method>.md
├── .agents/
│   └── skills -> ../.claude/skills    # Codex 用シンボリックリンク
├── docs/
│   ├── agent/                         # このリポジトリ固有の知識のみ（概要・データカタログ・指標定義）
│   └── gallery/                       # 診断図ギャラリー（GitHub Pages で公開。図はデモの出力をメンテナの手元で変換して配置）
├── data/
│   ├── raw/                           # 元データ（不変・gitignore対象）
│   ├── external/                      # 外部データ（不変・gitignore対象）
│   ├── interim/                       # 中間加工データ
│   └── processed/                     # 最終加工データ
├── notebooks/                         # 分析用Notebook
├── outputs/
│   ├── figures/                       # グラフ・図
│   ├── tables/                        # 集計テーブル
│   └── reports/                       # レポート
├── scripts/                           # CI・検証スクリプト
│   └── skill_eval/                    #   skill 発火テスト（run_skill_eval.py から手動実行）
├── src/analysis_project/              # 再利用可能なPythonモジュール
└── tests/                             # テスト

エージェント指示体系の設計

このリポジトリは GitHub Copilot・Claude Code・Codex の3つに対応しています。
どのツールを使っても同じルールが効くように、指示の実体は1か所にしか置かない方針を取っています。

ルーター文書（1つの内容を2ファイルで提供）

ツールごとに読むファイル名が決まっているため、ファイルは2つありますが内容は同一です。
## Hard Rules 以降が一致しているかは scripts/sync_agent_docs.py --check がCIで検証します。

スキルと補助ファイル

Copilot は .github/copilot-instructions.md も読めますが、VS Code / CLI / coding agent はいずれも
AGENTS.md に対応しているため、二重管理を避けて置いていません。AGENTS.md を読まない
IDE（JetBrains・Visual Studio・Xcode・Eclipse）で使う場合は、AGENTS.md と同内容の
.github/copilot-instructions.md を追加してください。

この設計により、全部入りの巨大な指示ファイルを避け、トークン効率よく必要な情報だけを参照できます。

利用可能なスキル（3ツール共通）

手法別診断 skill（*-diagnostics）

手法ごとに「実行したら必ずセットで出す図と値」を定義した skill 群です。LLM は「回帰したら残差を見るべき」と知っていても、頼まれたこと（当てはめて R² を報告）だけで診断を省きがちです。この skill 群は各手法について 図（何が見えれば合格か）・値（合格基準と違反時の対処）・落とし穴 を強制します。ユーザーが診断に言及しなくても、対応する手法を実行した時点で適用されます。

2 段構成（progressive disclosure） です。常にコンテキストに載るのは 5 つのルーターの description だけで、手法別の本文はルーターが選んだときにだけ読まれます。

.claude/skills/<family>-diagnostics/
├── SKILL.md            # 第 1 段: ルーター（約 70 行。ルーティング表・隣接 skill・「出力と報告」の共通書式）
└── references/
    └── <method>.md     # 第 2 段: 手法別（60〜140 行。適用範囲 / ライブラリ / 必ず出す図 / 必ず出す値 / 落とし穴）

• 置き場は .claude/skills/ の 1 か所だけです。Claude Code と Copilot は .claude/skills/ を直接読み、Codex は .agents/skills（.claude/skills へのシンボリックリンク）から読むので、3 ツールで同じ内容が使われます
• 各ディレクトリは他ファイルを参照しません。他リポジトリへは .claude/skills/<family>-diagnostics/ をディレクトリごとコピーするだけで使えます
• 図は outputs/diagnostics/<YYYYMMDD-HHMM>_<短縮名>/ に保存し（gitignore 済み）、報告には | 診断項目 | 実測値 | 合格基準 | 判定 | 次アクション | の表だけを載せます（判定は OK / 要対処 / 確認）
• 手法やルーターを追加する手順と雛形は docs/agent/diagnostics-reference-template.md
• skill が意図どおりに発火するか（頼んだ手法の references を読み、頼んでいない references は読まないか）は、scripts/skill_eval/ のハーネスで確かめられます。ケースごとに claude -p を起動するので手動で実行します（費用の目安は同 README）。CI では cases.yaml と references の整合性を見るテストだけが走ります
• 各 reference が「必ず出す」と定めた図を実データで出力したギャラリーを GitHub Pages で公開しています（5 スキル・17 手法・45 図。ソースは docs/gallery/）。.github/workflows/pages.yml でデプロイします
• references 内のコード抜粋が使うライブラリ（statsmodels / scikit-learn 1.8 / lifelines / cmdstanpy 2.39 など）は本リポジトリの pyproject.toml に含めていないので、使う手法に応じて uv add してください

今後の拡張候補（未作成）: トピックモデル（LDA・BERTopic）、深層学習の学習診断。推薦評価・公平性指標・ドリフト監視・データ品質検証は対象外です。

注意: Codex を使う場合、Windows で clone するときはシンボリックリンクを有効にしてください（git config core.symlinks true と開発者モード）。無効の環境では .agents/skills がリンク先パスを書いたテキストファイルになります。Claude Code と Copilot は .claude/skills/ を直接読むため影響ありません。

タスク実行用スキル（旧コマンド / プロンプト）

Claude Code では .claude/skills/*/SKILL.md として（/plan-analysis のようにスラッシュでも起動可能）、Copilot では引き続き .github/prompts/*.prompt.md として提供されるタスク実行用スキル。

エージェント文書の同期

skill 本体はミラーを持たないため、同期が必要なのは次の2種類だけです。

• ルーター文書: CLAUDE.md ⇔ AGENTS.md。## Hard Rules 以降の本文が完全に同一であること。冒頭の導入文と、CLAUDE.md にだけある ## Skills（skill の @ import）は各ファイル固有として比較対象外。
• タスク実行スキル（frontmatter に disable-model-invocation: true）: .claude/skills/<name>/SKILL.md ⇔ .github/prompts/<name>.prompt.md。frontmatter 形式を変換し、Copilot の ${input:...} プレースホルダや CLAUDE.md⇔AGENTS.md の相互参照を保持・変換しながら同期。

片方を編集すると差分が生じるため、以下の仕組みで検出・解消します。

• uv run python scripts/sync_agent_docs.py --check — 書き込みせず差分の有無だけを判定する（run_quality_checks.sh / CIに組み込み済み。ルーター文書の差分のみ終了コード1）。
• uv run python scripts/sync_agent_docs.py --from claude（または --from github） — 編集した側を明示してもう一方へ反映する。方向は必須（mtime による自動判定はしない）。元ファイルの改行コードは保持されます。
• /sync-agent-docs（Claude Code）・prompt（Copilot） — 上記スクリプトを実行した上で、対応するタスクスキルが無い prompt など、判断が必要な差分をエージェントが解消する。
• ロジックのテスト: uv run pytest tests/test_sync_agent_docs.py。

データの安全性ルール

• data/raw/ と data/external/ は不変として扱い、直接変更しない。
• rawデータ、認証情報、APIキー、トークン、顧客レベルのレコードをコミットしない。
• 加工データは data/interim/ や data/processed/ に出力する。
• 図表やレポートは outputs/ に出力する。
• .env ファイルは .gitignore でコミット対象外。

パッケージ管理

• uv のみを使用する。pip、conda、poetry は使わない。
• 依存関係の追加: uv add <package>
• 開発依存の追加: uv add --group dev <package>