Project conventions
Skill goonobu-dot/dev-skills-library/skills/project-conventions
15 auto-selectable Claude Code skills distilling engineering best practices (Kent Beck, Fowler, Google SRE, OWASP, Anthropic, Netflix…), with a bilingual offline learning site. Make Claude Code write better code — and learn the practices yourself.
npx -y skills add goonobu-dot/dev-skills-library --skill project-conventionsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 29 days oldThe repository was created 29 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Project scaffolding conventions from elsewhencode/project-guidelines: directory layout, env var and config management, README/CONTRIBUTING essentials, Git branch and commit conventions. Use when starting a new project/repository, restructuring project layout, setting up .env/.gitignore, or when the user says プロジェクト構成, 雛形, 新規リポジトリ, ディレクトリ構成. Not for writing the commit message itself (use commit-and-pr) or for CI/CD workflow design (use ci-cd-hardening).
SKILL.md
6.3 KB, as published. Nobody here has run it
Project Conventions
新規プロジェクトの雛形作成・既存プロジェクトの構造整理のためのスキル。ディレクトリ構成、環境変数管理、README/CONTRIBUTING、Gitブランチ規約を扱う。コミットメッセージそのものの書き方は commit-and-pr、CI/CDワークフローの設計は ci-cd-hardening を使う。
使うタイミング
- 新規プロジェクト・新規リポジトリを立ち上げるとき
- 既存プロジェクトのディレクトリ構造が乱雑で整理するとき
.env/ 設定管理の仕組みを導入するとき- README・CONTRIBUTINGの雛形を作るとき
- Gitのブランチ運用ルールを決めるとき
手順
ステップ1：ディレクトリ構成を機能単位で分ける
- ページ・機能単位（例：
product/,user/,order/）でディレクトリを分け、実装ファイルとテストファイルを同階層に併置する（src/とtest/を完全分離しない方が、関連ファイルを見失いにくい）。 - 設定ファイルは
./configに集約する（環境ごとの設定を1箇所にまとめ、散在させない）。 - 補助スクリプト（マイグレーション、シード投入、ビルド補助）は
./scriptsに集約する。 - ビルド成果物は
./build（または./dist）に出力し、必ず.gitignoreへ登録する。 - 巨大な1ファイル（数千行の
utils.js等）を作らない。責務ごとにファイルを分割する。
ステップ2：環境変数・設定管理を安全にする
- 機密情報（APIキー、接続文字列、トークン）は
.envに記載し、.gitignoreへ登録する。絶対にコミットしない。 .env.exampleにキー名のみのテンプレート（値は空またはダミー）を用意し、これはリポジトリにコミットする。新規参加者が何を設定すべきか一目でわかるようにする。- アプリ起動時に環境変数のスキーマバリデーション（例：
joi,zod,pydantic-settings等プロジェクトの言語に合うもの）を行い、必須変数の欠落を起動直後に検知する。実行中に初めて気づく設計にしない。 - 環境ごと（development/staging/production）で異なる値は環境変数側で切り替え、コード側にif分岐で環境名を埋め込まない。
ステップ3：README / CONTRIBUTINGの必須要素
README.mdに最低限含める項目：
- プロジェクトの目的（1〜2文）
- セットアップ手順（依存関係インストール〜起動まで、コピペで動く形）
- 必要な環境変数一覧（
.env.exampleへのリンクでも可） - テスト実行コマンド
- ディレクトリ構成の簡単な説明
CONTRIBUTING.mdに最低限含める項目：
- ブランチ運用ルール
- コミットメッセージ規約（詳細はcommit-and-pr参照でよい）
- PR作成前に実行すべきチェック（lint、テスト）
- コードスタイル・レビュー基準へのリンク
ステップ4：Gitブランチ運用規約を決める
main（またはdevelop）から feature ブランチを切る。main/developへの直接pushは禁止し、PR必須にする。- マージ前に対話的リベース等でコミット履歴を整理する（無意味な"wip"コミットの羅列を残さない）。
- マージ後はローカル・リモート双方のfeatureブランチを削除する（ブランチが溜まり続けるのを防ぐ）。
- ブランチ命名規則を統一する（例：
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ワークフロー規約を要約・手順化。