project-structure-guide

# Project Structure Guide > **Language**: English | [繁體中文](../../locales/zh-TW/skills/project-structure-guide/SKILL.md) **Version**: 1.1.0 **Last Updated**: 2026-03-04 **Applicability**: Claude Code Skills --- ## Purpose This skill provides guidance on structuring projects according to language and framework conventions. It helps create consistent, maintainable directory layouts. # [Physical Binding] ## Reality Check Before confirming the project structure is valid, you MUST: 1. Run the validator: `uds check --standard project-structure` 2. IF exit_code != 0: - Read the error message (e.g., "Missing required directories"). - Report the violation to the user. - Suggest specific commands (`mkdir ...`) to fix it. - RETRY validation after fixes are applied. ## Trigger Use this skill when: - Creating a new project - Reorganizing existing project structure - Adding new modules or features - Setting up build configuration - Creating .gitignore files - Deciding where to place a file (code, docs, config, asset) - Choosing between utils/, helpers/, shared/, lib/, or internal/ - Placing development artifacts (brainstorms, RFCs, POCs, investigations) ## Supported Languages | Language | Frameworks/Patterns | |----------|---------------------| | Node.js | Express, NestJS, Next.js | | Python | Django, Flask, FastAPI | | Java | Spring Boot, Maven, Gradle | | .NET | ASP.NET Core, Console | | Go | Standard layout, cmd/pkg | | Rust | Binary, Library, Workspace | | Kotlin | Gradle, Android, Multiplatform | | PHP | Laravel, Symfony, PSR-4 | | Ruby | Rails, Gem, Sinatra | | Swift | SPM, iOS App, Vapor | ## Common Structure Patterns ### Standard Directories ``` project-root/ ├── src/ # Source code ├── tests/ # Test files ├── docs/ # Documentation ├── tools/ # Build/deployment scripts ├── examples/ # Usage examples ├── config/ # Configuration files └── .github/ # GitHub configuration ``` ### Build Output (Always gitignore) ``` dist/ # Distribution output build/ # Compiled artifacts out/ # Output directory bin/ # Binary executables ``` ## Language-Specific Guidelines ### Node.js ``` project/ ├── src/ │ ├── index.js │ ├── routes/ │ ├── controllers/ │ ├── services/ │ └── models/ ├── tests/ ├── package.json └── .gitignore ``` ### Python ``` project/ ├── src/ │ └── package_name/ │ ├── __init__.py │ └── main.py ├── tests/ ├── pyproject.toml └── .gitignore ``` ### Go ``` project/ ├── cmd/ │ └── appname/ │ └── main.go ├── internal/ ├── pkg/ ├── go.mod └── .gitignore ``` ## Quick Actions ### Create Project Structure When asked to create a project: 1. Ask for language/framework 2. Generate appropriate directory structure 3. Create essential config files 4. Generate .gitignore ### Review Structure When reviewing existing structure: 1. Check language conventions 2. Verify gitignore patterns 3. Suggest improvements 4. Identify misplaced files ## Rules 1. **Follow language conventions** - Each language has established patterns 2. **Separate concerns** - Keep source, tests, docs separate 3. **Gitignore build outputs** - Never commit dist/, build/, out/ 4. **Consistent naming** - Use language-appropriate casing 5. **Config at root** - Place config files at project root 6. **Disambiguate directories** - utils/ (stateless, generic), helpers/ (layer-bound), shared/ (cross-module), lib/ (wrapped deps) 7. **Working docs in docs/working/** - Brainstorms, RFCs, POCs, investigations go in docs/working/ with lifecycle management 8. **Generated code separated** - Place in src/generated/{type}/, never mix with hand-written code ## Next Steps Guidance | 下一步引導 After `/project-structure` completes, the AI assistant should suggest: > **專案結構已建立或審查完成。建議下一步 / Project structure created or reviewed. Suggested next steps:** > - 執行 `/sdd` 開始規格驅動開發，將專案結構納入正式規格 ⭐ **Recommended / 推薦** — 確保結構決策有規格追蹤 / Ensures structure decisions are tracked in specs > - 執行 `/docs` 產生專案文件（README、ARCHITECTURE.md 等） — 讓結構決策有文件記錄 / Document structure decisions > - 執行 `/ai-friendly-architecture` 設定 AI 上下文配置 — 讓 AI 助手更好地理解專案結構 / Help AI assistants understand the project structure --- ## Related Standards - [Language-specific patterns](./language-patterns.md) — concrete directory layouts per language (Node.js/TypeScript, Python, Go, and others). Read it when laying out a project in a specific language. - [Core: Project Structure](../../core/project-structure.md) - [Core: Documentation Structure](../../core/documentation-structure.md) - [Guide: File Placement Decision Guide](../../core/guides/file-placement-guide.md) - [AI: Project Structure Options](../../ai/options/project-structure/)