Project conventions

Project Conventions

新規プロジェクトの雛形作成・既存プロジェクトの構造整理のためのスキル。ディレクトリ構成、環境変数管理、README/CONTRIBUTING、Gitブランチ規約を扱う。コミットメッセージそのものの書き方は commit-and-pr、CI/CDワークフローの設計は ci-cd-hardening を使う。

使うタイミング

• 新規プロジェクト・新規リポジトリを立ち上げるとき
• 既存プロジェクトのディレクトリ構造が乱雑で整理するとき
• .env / 設定管理の仕組みを導入するとき
• README・CONTRIBUTINGの雛形を作るとき
• Gitのブランチ運用ルールを決めるとき

手順

ステップ1：ディレクトリ構成を機能単位で分ける

1. ページ・機能単位（例：product/, user/, order/）でディレクトリを分け、実装ファイルとテストファイルを同階層に併置する（src/とtest/を完全分離しない方が、関連ファイルを見失いにくい）。
2. 設定ファイルは ./config に集約する（環境ごとの設定を1箇所にまとめ、散在させない）。
3. 補助スクリプト（マイグレーション、シード投入、ビルド補助）は ./scripts に集約する。
4. ビルド成果物は ./build（または./dist）に出力し、必ず .gitignore へ登録する。
5. 巨大な1ファイル（数千行のutils.js等）を作らない。責務ごとにファイルを分割する。

ステップ2：環境変数・設定管理を安全にする

1. 機密情報（APIキー、接続文字列、トークン）は .env に記載し、.gitignore へ登録する。絶対にコミットしない。
2. .env.example にキー名のみのテンプレート（値は空またはダミー）を用意し、これはリポジトリにコミットする。新規参加者が何を設定すべきか一目でわかるようにする。
3. アプリ起動時に環境変数のスキーマバリデーション（例：joi, zod, pydantic-settings等プロジェクトの言語に合うもの）を行い、必須変数の欠落を起動直後に検知する。実行中に初めて気づく設計にしない。
4. 環境ごと（development/staging/production）で異なる値は環境変数側で切り替え、コード側にif分岐で環境名を埋め込まない。

ステップ3：README / CONTRIBUTINGの必須要素

README.mdに最低限含める項目：

• プロジェクトの目的（1〜2文）
• セットアップ手順（依存関係インストール〜起動まで、コピペで動く形）
• 必要な環境変数一覧（.env.exampleへのリンクでも可）
• テスト実行コマンド
• ディレクトリ構成の簡単な説明

CONTRIBUTING.mdに最低限含める項目：

• ブランチ運用ルール
• コミットメッセージ規約（詳細はcommit-and-pr参照でよい）
• PR作成前に実行すべきチェック（lint、テスト）
• コードスタイル・レビュー基準へのリンク

ステップ4：Gitブランチ運用規約を決める

1. main（またはdevelop）から feature ブランチを切る。main/developへの直接pushは禁止し、PR必須にする。
2. マージ前に対話的リベース等でコミット履歴を整理する（無意味な"wip"コミットの羅列を残さない）。
3. マージ後はローカル・リモート双方のfeatureブランチを削除する（ブランチが溜まり続けるのを防ぐ）。
4. ブランチ命名規則を統一する（例：feature/xxx, fix/xxx, chore/xxx）。

チェックリスト（新規プロジェクト立ち上げ時）

• 機能単位のディレクトリ構成になっているか（技術レイヤー単位だけで分割していないか）
• .gitignore に .env・ビルド成果物・依存関係ディレクトリが含まれているか
• .env.example が用意されているか
• 起動時の環境変数バリデーションが入っているか
• README単体でセットアップが完結するか（口頭説明が前提になっていないか）
• ブランチ運用ルールがCONTRIBUTINGに明文化されているか

アンチパターン集

アンチパターン	現実
.envを誤ってコミットする	秘密情報が履歴に残り続け、削除してもgit historyから完全除去は困難。最初から.gitignoreに入れる
環境変数の必須チェックをしない	本番デプロイ後、特定の機能を使った瞬間に初めて「変数が未設定」と気づく。起動時バリデーションで早期検知する
README に「詳しくは担当者に聞いてください」と書く	新規参加者・将来の自分・AIエージェントがセットアップできない。手順は自己完結させる
技術レイヤー単位（controllers/, models/, views/)だけでディレクトリを切る	1機能の変更が複数ディレクトリに分散し、関連ファイルを探すコストが増える。機能単位との併用を検討する
ブランチを削除せず放置する	リポジトリが肥大化し、どのブランチが生きているか判別できなくなる。マージ後は必ず削除する
環境ごとの分岐をコード内にif (env === "production")で書き散らす	環境差分がコードとconfigの両方に散らばり、変更時に見落としが発生する。configに集約する

出典

• elsewhencode/project-guidelines（MIT License）— ディレクトリ構成、環境変数管理、Gitワークフロー規約を要約・手順化。