init-python-project

Python プロジェクトを初期化する

このスキル内に大きなファイル本文を直接記述せずに、本番環境に対応した Python プロジェクトの作成や、既存プロジェクトのアップグレードを支援します。同梱のリファレンスとテンプレートを信頼できる情報源として使用してください。Python ツールチェーンは明示的なゲートとして扱います。デフォルトでは変更を加えないチェックを行い、フォーマットや修正のコマンドは、要求された場合または必要な場合にのみ実行し、実際に実行したコマンドをリポジトリのガイダンスに記録してください。コード、シェル、シークレット、ノートブック、設定ファイル、GitHub Actions、ドキュメントのリンクに対する任意のローカルゲートランナーとして pre-commit を使用してください。

スキルのディレクトリ構成

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── architecture.md
│   ├── new-project.md
│   ├── fork-enhancement.md
│   └── best-practices.md
├── scripts/
│   └── scaffold_new_project.py
├── template_manifest.json
└── templates/
    ├── common/
    │   ├── .gitignore
    │   ├── .env.example
    │   ├── README.md
    │   ├── AGENTS.md
    │   ├── CLAUDE.md
    │   ├── pyproject.toml.tmpl
    │   ├── tests/
    │   └── docs/
    └── ml/
        ├── .agent/
        ├── docs/
        ├── experiments/
        ├── infra/
        ├── eval/
        └── scripts/

段階的な読み込み

現在の作業に必要なリファレンスのみを読みます。

• references/architecture.md は必ず読みます
• 新規プロジェクトの場合は、references/new-project.md を読みます
• フォークまたは機能追加の場合は、references/fork-enhancement.md を読みます
• ポリシー、トレードオフ、障害対応に関するガイダンスが必要な場合は、references/best-practices.md を読みます

長いコード片をインラインで記述するのではなく、ファイルの内容に関する信頼できる情報源として templates/ を使用してください。 スキャフォールドでサポートされるテンプレートグループとプレースホルダーの信頼できる情報源として、template_manifest.json を使用してください。

ステップ 1 — プロジェクト情報を収集する

次の内容を 1 つのメッセージでユーザーに尋ねます。

1. プロジェクトの種類：
   • new — 新しいプロジェクトを作成する
   • fork — 既存のリポジトリをクローンして機能を追加する
2. new の場合：
   • プロジェクト名
   • パッケージ名（デフォルト：プロジェクト名の snake_case 形式）
   • 簡単な説明
   • Python のバージョン（デフォルト：3.11）
   • プロジェクトの種類：ml、web、lib、または general
3. fork の場合：
   • GitHub リポジトリの URL
   • フォークのワークフローを希望するか、ローカルでの機能追加のみを希望するか
4. どちらの場合も：
   • 対象リポジトリの GitHub リポジトリ URL（利用できる場合）
   • 作者名とメールアドレス
   • 既存のツールチェーンポリシー（ある場合）：ruff、black、isort、mypy、pyright、pytest、pre-commit、gitleaks、shellcheck、shfmt、actionlint、nbstripout、CI、またはカスタムコマンド

回答を待ってから続行します。

ステップ 2 — 実行パスを選択する

パス A：新規プロジェクト

references/new-project.md と references/architecture.md を読みます。

2A.1 プロジェクトのルートを作成する

mkdir <project-name>
cd <project-name>
uv init --name <package_name> --python <version>

ディレクトリがすでに存在する場合は、別の名前を選ぶか、既存のディレクトリを再利用するかを尋ね、作業を停止します。

2A.2 new + ml の推奨パス

新しい ML プロジェクトでは、同梱のスキャフォールドスクリプトを優先してください。

python3 <installed-skill-dir>/scripts/scaffold_new_project.py \
  <target-dir> \
  --project-name <project-name> \
  --package-name <package-name> \
  --description "<short-description>" \
  --python-version <version> \
  --author-name "<author-name>" \
  --author-email "<author-email>" \
  --repo-url "<repo-url-or-TBD>"

このスクリプトは、次の処理を行います。

• uv init
• ソース、テスト、ドキュメント用ディレクトリの作成
• templates/common/ と templates/ml/ からのテンプレートのコピー
• プレースホルダーの置換
• .env の作成
• ローカルからリモートへのワークフロー用リモートプロジェクトのメモリーファイルの初期化
• .gitkeep ファイルの書き込み

完了後、ステップ 2A.6 と 2A.7 のインストール、検証、Git のセットアップを続行します。

ユーザーが ML 以外の構成を希望する場合、またはスクリプトが適切でない場合は、以下の手動パスに切り替えます。

2A.3 手動での代替手順：ディレクトリ構成を作成する

ml プロジェクトでは、references/architecture.md に記載された 4 層構造をすべて作成します。

最低限、次の構成を作成します。

mkdir -p src/<package_name>/{models,data,utils}
mkdir -p tests/{data,outputs}
mkdir -p docs/outlines docs/dev/features docs/src docs/results docs/reports docs/runs
mkdir -p .vscode .cursor .claude/commands
touch src/<package_name>/__init__.py
touch src/<package_name>/models/__init__.py
touch src/<package_name>/data/__init__.py
touch src/<package_name>/utils/__init__.py
touch tests/__init__.py

ML 以外のプロジェクトでは、共通のプロジェクトファイルを維持し、ユーザーが明示的に希望した場合にのみ ML 固有のディレクトリを作成します。

2A.4 テンプレートを具体化する

templates/ 内のテンプレートを使用し、プレースホルダーを置き換えます。

• {{PROJECT_NAME}}
• {{PACKAGE_NAME}}
• {{DESCRIPTION}}
• {{PYTHON_VERSION}}
• {{AUTHOR_NAME}}
• {{AUTHOR_EMAIL}}
• {{REPO_URL}}

templates/common/ から以下の共通ファイルを書き込みます。

• .gitignore
• .env.example
• README.md
• AGENTS.md
• CLAUDE.md
• .pre-commit-config.yaml
• pyproject.toml
• tests/conftest.py
• docs/outlines/project_plan.md
• docs/outlines/progress.md
• docs/results/.gitkeep
• docs/reports/.gitkeep
• docs/runs/.gitkeep
• docs/dev/feature_template.md
• docs/src/dependencies.md
• .vscode/settings.json

ml プロジェクトでは、以下も書き込みます。

• experiments/config.py
• experiments/configs/base.yaml
• infra/envs/local.yaml
• infra/envs/cluster.yaml.example
• infra/remote-projects.yaml
• infra/README.md
• docs/ops/current-status.md
• docs/ops/decision-log.md
• .agent/local-overrides.yaml
• eval/baselines/README.md
• scripts/train.py
• scripts/download_data.py

.env が存在しない場合は、短いコメントヘッダーを含む空のファイルとして作成します。

2A.5 空のディレクトリにプレースホルダーファイルを追加する

空のディレクトリを追跡対象にする必要がある場合は、.gitkeep を使用します。

touch experiments/configs/.gitkeep
touch eval/benchmarks/.gitkeep
touch eval/baselines/reproduced/.gitkeep
touch infra/submit/slurm/.gitkeep
touch docs/results/.gitkeep
touch docs/reports/.gitkeep
touch docs/runs/.gitkeep
touch tests/data/.gitkeep
touch tests/outputs/.gitkeep

選択したプロジェクトタイプで実際に存在するディレクトリにのみ、プレースホルダーを作成します。

2A.6 ツールチェーンのゲートをインストールして検証する

このコードリポジトリがプロジェクト管理ルートのレイアウト（兄弟ディレクトリとして <ProjectName>/code/ と <ProjectName>/code-worktrees/ がある構成）の一部である場合は、uv sync または uv run コマンドを実行する前に、共有の project-code uv 環境を使用します。

export UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code

このポリシーでは、相対パスの UV_PROJECT_ENVIRONMENT を使用しないでください。uv は相対値を各アクティブなワークスペースルートからの相対パスとして解決するため、ワークツリーごとに別々の環境が作成される可能性があります。Python のエントリーポイントは、共有環境の bin/python を直接呼び出すのではなく、アクティブなワークツリーから uv run を通じて実行してください。依存関係、Python/CUDA スタック、破壊的なパッケージテスト、または実際に同時実行する同期処理のリスクがある場合に限り、別のステージ環境を使用し、その例外をワークツリーまたはプロジェクトのガイダンスに記録します。

ML プロジェクトの場合：

uv sync
uv pip install -e ".[dev,ml]"

ML 以外のプロジェクトの場合：

uv sync
uv pip install -e ".[dev]"

デフォルトの非変更ゲートを実行します。選択したプロジェクトタイプに存在しないパスは省略します。

uv run ruff format --check src tests experiments scripts
uv run ruff check src tests experiments scripts
uv run mypy src
uv run pytest tests -v
uv run pre-commit run --all-files

テストがまだない場合は、プレースホルダーテストを作成して再実行します。

cat > tests/test_placeholder.py <<'EOF'
def test_placeholder():
    assert True
EOF
uv run pytest tests/

uv run ruff format ...、uv run ruff check --fix ...、shfmt -w、--dry-run を付けない nbstripout、またはその他の変更を伴う修正コマンドを、黙って実行しないでください。変更を伴うコマンドは、ユーザーがフォーマットや修正を依頼した場合、または文書化されたプロジェクトポリシーで必要とされる場合にのみ使用し、その後、差分を確認します。

2A.7 git とオプションのリモートを初期化する

git rev-parse --git-dir >/dev/null 2>&1 || git init
git add .
git commit -m "Initial Python project structure"

ユーザーから GitHub URL が提供された場合は、origin を追加し、git remote -v を表示してから、プッシュする前に確認を求めます。

git remote add origin <github-ssh-url>
CURRENT_BRANCH="$(git branch --show-current)"
project-push --set-upstream . origin "$CURRENT_BRANCH"

パス B：フォーク／既存プロジェクト

references/fork-enhancement.md、references/architecture.md、references/best-practices.md を読みます。

2B.1 クローンして調査する

git clone <github-ssh-url> <project-name>
cd <project-name>
ls -la

以下を確認します。

• pyproject.toml、setup.py、requirements.txt
• src/、tests/、docs/、scripts/
• .env.example、AGENTS.md、CLAUDE.md、.vscode/settings.json

2B.2 大規模な編集の前に不足点を報告する

以下を示す簡潔なレポートを作成します。

• 既存の構成
• 重要度の高い不足コンポーネント
• リポジトリがすでにインストール可能かどうか
• すでに存在するツールチェーンのゲート
• ドキュメント／テストの分離が不足しているかどうか

その後、以下のどれを行うか尋ねます。

1. 不足しているコンポーネントをすべて追加する
2. 選択したコンポーネントのみを追加する
3. 編集せずにチェックリストを生成する

2B.3 不足しているコンポーネントのみを追加する

ユーザーが編集を承認したら、templates/common/ のテンプレートを使って不足分を補います。

• .env.example
• AGENTS.md
• CLAUDE.md
• .pre-commit-config.yaml
• tests/conftest.py
• docs templates
• .vscode/settings.json
• requirements.txt から移行する場合は pyproject.toml

ユーザーが明示的に移行を希望しない限り、既存のリポジトリに ML 向けのレイアウト全体を無理に適用しないでください。 既存の健全なツールチェーンを維持してください。新しいスキャフォールドのデフォルトが ruff、mypy、pytest、ローカルの pre-commit フックだからという理由だけで、black、isort、pyright、pre-commit、gitleaks、shellcheck、shfmt、actionlint、nbstripout、CI コマンドを置き換えないでください。

テンプレート適用ルール

• 既存の内容の充実したファイルが十分に適切であれば、そのまま維持してください。
• 上書きするより、必要な箇所だけを編集してください。
• テンプレート化されたファイルでは、プレースホルダーを一貫して置き換えてください。
• テンプレートが部分的にしか関連しない場合は、ファイル全体をそのままコピーせず、関連するセクションだけをコピーしてください。

最終サマリー

以下を報告してください。

✓ Python project initialized or enhanced: <project-name>
✓ Project type: <new|fork> / <ml|web|lib|general>
✓ Common scaffolding applied
✓ UV environment configured
✓ Toolchain gates configured: format / lint / type-check / test / secrets / shell / notebooks / configs / docs links
✓ Git status: initialized / existing repo reused
✓ Remote: <configured or skipped>

Project location: <full-path>

Next steps:
1. cd <project-name>
2. cp .env.example .env
3. Fill in project-specific settings
4. Start implementing in src/<package_name>/
5. Put stable experiment summaries in docs/results/, reports in docs/reports/, and run pointers in docs/runs/
6. Run the toolchain gates before the next commit:
   `uv run ruff format --check src tests experiments scripts`
   `uv run ruff check src tests experiments scripts`
   `uv run mypy src`
   `uv run pytest tests -v`
   `uv run pre-commit run --all-files`

重要な注意事項

• エッジケースに遭遇した場合は、references/best-practices.md を参照してください。
• この SKILL.md はオーケストレーションに重点を置き、詳細なファイルの内容は templates/ と references/ に記載してください。
• experiments/ は実行可能な実験ロジックを置く場所であり、結果のアーカイブではありません。生の出力、チェックポイント、ログ、wandb/tensorboard のキャッシュは、無視対象のパスまたは外部ストレージに置き、docs/runs/ には簡潔な参照情報を記録してください。
• このコードリポジトリがプロジェクト管理ルートに属する場合は、code/ 内にネストされたワークツリーを作成するのではなく、<ProjectName>/code-worktrees/ 内に兄弟としてコードワークツリーを作成してください。
• プリフライト後に通常の最終ブランチプッシュを行う場合は、生の git push、git -C <repo> push、cd <repo> && git push、またはシェルでラップしたプッシュの代わりに、project-push <repo> <remote> <branch> を使用してください。
• このコードリポジトリがプロジェクト管理ルートに属する場合は、ツールチェーンのゲートコマンドをルートの memory/project.yaml とコンポーネントのガイダンスに記録してください。現在のブランチ／ワークツリーで検証されていないゲートの状態は古いものとして扱ってください。