project-bootstrap

プロジェクトの初期設定

概要

プロジェクトを適切に初期化しておけば、将来的な構造上の悩みの80％を防げます。

基本原則： 今すぐセットアップに30分かけるか、後で構造的負債の解消に30時間かけるかです。

例外なし。回避策なし。近道なし。

最優先事項

NO FEATURE CODE BEFORE PROJECT STRUCTURE IS ESTABLISHED

プロジェクトにリンティング、フォーマット、テスト基盤、バージョン管理の適切な運用が欠けている場合は、ビジネスロジックを書く前にその不足を解消してください。

使用する場面

必須となる場面：

• ゼロから新しいプロジェクトを作成するとき
• 「とにかく動くものを作る」とき（特にこの場合）
• 本番環境へ発展する可能性のあるプロトタイプを構築するとき
• チームで共有するリポジトリをセットアップするとき

以下の場合にも適用できます：

• 構造的な基盤がないプロジェクトを引き継ぐとき
• テストされていないコードにテスト基盤を後付けするとき
• 初めて CI/CD を導入するとき

導入手順

BEFORE writing any feature code:

1. STRUCTURE: Is the directory layout established?
2. TOOLING: Are linter, formatter, and type checker wired up?
3. TESTING: Is the test runner configured with a passing placeholder?
4. VERSION CONTROL: Are .gitignore, branch conventions, and hooks set up?
5. DEPENDENCIES: Is the package manager initialized with a committed lockfile?
6. AUTOMATION: Does at minimum a lint + test pipeline exist?

If any answer is NO: fix it first.

プロジェクトの分類

digraph project_class {
    start [label="What is being\nbuilt?", shape=diamond];
    web [label="Web\napplication?", shape=diamond];
    api [label="API /\nbackend?", shape=diamond];
    cli [label="CLI tool?", shape=diamond];
    lib [label="Library /\npackage?", shape=diamond];

    web_tpl [label="Web App\nBlueprint", shape=box, style=filled, fillcolor="#ccffcc"];
    api_tpl [label="API\nBlueprint", shape=box, style=filled, fillcolor="#ccccff"];
    cli_tpl [label="CLI\nBlueprint", shape=box, style=filled, fillcolor="#ffffcc"];
    lib_tpl [label="Library\nBlueprint", shape=box, style=filled, fillcolor="#ffccff"];
    general [label="General\nBlueprint", shape=box, style=filled, fillcolor="#ffcccc"];

    start -> web [label="assess"];
    web -> web_tpl [label="yes"];
    web -> api [label="no"];
    api -> api_tpl [label="yes"];
    api -> cli [label="no"];
    cli -> cli_tpl [label="yes"];
    cli -> lib [label="no"];
    lib -> lib_tpl [label="yes"];
    lib -> general [label="no"];
}

プロジェクトの分類ごとの詳細なセットアップチェックリストは、templates.mdを参照してください。

全プロジェクト共通の基盤

1. バージョン管理の適切な運用

.gitignore          # Language-specific + universal exclusions
.gitattributes      # Line ending normalization, binary file handling

必須の .gitignore エントリ：

• node_modules/、venv/、__pycache__/、target/（依存関係のディレクトリ）
• .env、.env.local、.env.*.local（秘密情報と認証情報）
• *.log（ログファイル）
• .DS_Store、Thumbs.db（OS の生成物）
• IDE のディレクトリ：.idea/、.vscode/（設定を意図的に共有する場合を除く）
• ビルド出力：dist/、build/、out/

2. 静的解析とフォーマット

言語	リンター	フォーマッター
TypeScript/JavaScript	ESLint	Prettier
Python	Ruff（リンティング＋フォーマット）	Ruff
Go	golangci-lint	gofmt（組み込み）
Rust	clippy	rustfmt（組み込み）
Ruby	RuboCop	RuboCop

初日にインストールしてください。 10,000行を書いた後にリンターを導入すると、初回実行で何百もの違反に対処することになります。

3. テスト基盤

言語	フレームワーク	ランナー
TypeScript/JavaScript	Vitest または Jest	組み込み
Python	pytest	組み込み
Go	testing（標準ライブラリ）	go test
Rust	組み込みテストハーネス	cargo test
Ruby	RSpec または Minitest	組み込み

すぐにテストを1つ作成し、成功させてください。 これにより、実際に必要になる前にテストパイプラインが機能することを確認できます。

4. 型安全性

言語	要件
TypeScript	tsconfig.json でstrict: trueを設定します。必須です。
Python	型アノテーション＋mypy または pyright
JavaScript	TypeScript の使用を検討してください。使用しない場合でも、最低限 JSDoc の型アノテーションを使ってください。

5. 継続的インテグレーションの最低要件

すべてのプロジェクトに、最低限、以下が必要です。

# Minimum CI pipeline (GitHub Actions example)
on: [push, pull_request]
jobs:
  check:
    steps:
      - lint
      - type-check
      - test

CI で実行されなければ、メンテナンスされなくなります。

ディレクトリ構成の原則

ファイルの種類ではなく、機能ごとに整理してください（godmode:system-designを参照）。

すべてのプロジェクトに必要なもの：

project-root/
  src/              # Source code (or lib/, app/ per convention)
  tests/            # Test files (or co-located alongside source)
  docs/             # Documentation (when applicable)
  scripts/          # Build, deploy, and utility scripts
  .gitignore
  README.md         # Purpose, installation, how to run
  <config files>    # Linter, formatter, CI, package manager

テストを同じ場所に置くか、別のディレクトリに置くか：

• 同じ場所に置く（payment.ts＋payment.test.ts）：保守しやすく、デフォルトとして推奨
• 別の場所に置く（tests/）：テストで共有フィクスチャが必要な場合、またはチームの規約で定められている場合

依存関係の管理

BEFORE adding any dependency:

1. Is it genuinely necessary? Could you write it in under 50 lines?
2. Is it actively maintained?
3. How many transitive dependencies does it introduce?
4. Does it carry known vulnerabilities?

When uncertain, write the code yourself.

必ず行うこと：

• ロックファイル（package-lock.json、poetry.lock、Cargo.lock）をコミットする
• メジャーバージョンを固定し、パッチレベルの更新は許可する
• CI でセキュリティ監査を実行する

認知上の落とし穴

正当化の言葉	実態
「ただのプロトタイプだから」	プロトタイプは本番環境へ進みます。適切に初期化してください。
「リンティングは後で追加する」	10,000行を書いた後では、何百もの違反に直面します。今やるほうが常に簡単です。
「テストが初期開発を遅らせる」	テストのセットアップは5分で済みます。テストなしでバグを探すと何時間もかかります。
「このプロジェクトに CI は大げさだ」	CI は忘れたことを検出します。初日に設定してください。
「ファイルの整理は後でやる」	後ではやりません。ディレクトリ構成はコードより変更が困難です。
「.gitignore の設定は後回しでいい」	.envファイルを1つコミットするだけで、認証情報が漏洩します。最初に設定してください。

ガードレール — 作業を止めてセットアップする

• リンターを設定せずに機能を開発している
• リポジトリに .gitignore がない
• テストフレームワークがインストールされていない
• シークレットをバージョン履歴にコミットしている（一度でも、削除した後でも、git の履歴に残り続けます）
• プロジェクトの実行方法を説明する README がない
• ビルド成果物が git にチェックインされている
• CI パイプラインがない
• あらゆる場所で any 型を使っている（TypeScript）

このリストの項目が一つでも当てはまる場合は、機能開発を中断してください。まず基盤を整えましょう。

連携

補完的なスキル：

• godmode:system-design -- ディレクトリ構成と技術選定
• godmode:quality-enforcement -- 最初から CI に品質ゲートを組み込む
• godmode:security-protocol -- シークレット管理と .gitignore の徹底
• godmode:ux-patterns -- UI プロジェクトのデザインシステム初期化

結論

30 minutes of setup now > 30 hours of structural debt later

リンター。フォーマッター。テスト。CI。.gitignore。README。最初の機能を開発する前に。毎回必ず。