| name | project-arch-core |
| description | Language-agnostic project architecture principles for AI-assisted development. Use when creating or reviewing language-specific arch skills, or when evaluating whether a codebase needs restructuring. Not a substitute for language-specific skills — provides the shared foundation they build on. |
Project Architecture Core — AI-Friendly Development
Language-agnostic architecture principles that keep codebases small enough for AI agents to read and edit efficiently.
When to Apply
✅ Apply when:
- Building a web service, API, or full-stack app with multiple files
- Codebase has grown past ~500 lines total
- AI agent is hitting context limits or making edit errors on large files
- Creating a new
<lang>-project-arch skill
❌ Don't apply when:
- One-off scripts or utilities under ~200 lines — just keep it in one file
- Prototyping / POC phase — premature splitting slows you down, refactor later
- Framework has strong conventions (Next.js app router, Django apps, Rails) — follow the framework first, apply these principles where the framework is silent
- Pure libraries with no runtime (config externalization / admin dashboard don't apply)
Core Principles
1. File Size Limits
- Source file ≤ 400 lines — beyond this, AI context usage spikes and edit accuracy drops
- Entry point ≤ 100 lines — only wiring/mounting, zero business logic
- HTML/template files ≤ 200 lines — skeleton only, logic in separate files
2. Entry Point = Wiring Only
The main entry file does exactly three things:
- Initialize dependencies (DB, middleware, plugins)
- Mount modules / register handlers
- Start the process
No business logic, no handler implementations, no data processing.
3. Config Externalization
- All tunable values in a config file (
config.json, .env, config.yaml, etc.)
- Loaded at runtime, never hardcoded
- Editable without code changes or restarts (hot-reload preferred for web services)
- Secrets stripped before exposing to frontend/clients
4. Layered Separation
Separate interface (how users/systems talk to you) from logic (what you do) from data (where you store it):
Entry (wiring) → Interface → Logic → Data
Common mappings:
| Project Type | Interface | Logic | Data |
|---|
| Web service | Routes / Handlers | Services | DB / API clients |
| CLI tool | Commands / Args parser | Services | File I/O / DB |
| Worker / Queue | Consumers / Listeners | Services | DB / Message queue |
| Desktop app | Views / Controllers | Services | Local storage / API |
5. Observability & Admin
For web services and long-running processes:
- Auth-protected admin interface for config editing + hot-reload
- Runtime stats (uptime, memory, request counts)
- Key business metrics
- Operation log
For CLIs and libraries: not required. Use logging and --verbose flags instead.
6. Frontend Splitting (if applicable)
- HTML = structure only (no inline JS/CSS beyond minimal bootstrap)
- CSS in separate files
- JS split by responsibility (each ≤ 400 lines)
Splitting Decision Guide
See references/splitting-guide.md for a language-agnostic decision flow:
- When to split vs. when to leave alone
- How to identify split boundaries
- Post-split verification checklist
Why This Matters for AI
| Scenario | Tokens per read | Context usage (200K) |
|---|
| 3000-line monolith | ~40K | 20% |
| 200-line module | ~2.7K | 1.3% |
Splitting files → 10-15 productive AI rounds vs 3-5 with monoliths. 70-93% token savings per file read.
Language-Specific Skills
This skill provides the universal foundation. For concrete directory structures, code patterns, and framework-specific rules, use the appropriate language skill:
| Language/Framework | Skill | Status |
|---|
| Node.js (Express) | nodejs-project-arch | ✅ Available |
| React / Vite | react-project-arch | ✅ Available |
| Python (FastAPI/Flask) | python-project-arch | 🔲 Community welcome |
| Go | go-project-arch | 🔲 Community welcome |
Creating a New Language Skill
If you're building a <lang>-project-arch skill, follow these core principles and add:
- Concrete directory structure — not abstract, copy-pasteable
- Entry point pattern — actual code showing wiring-only entry
- Config pattern — language-idiomatic config loading + hot-reload
- Splitting rules table — "this monolith → these modules" with max lines
- Project type references — separate files for different project types
Keep the same naming convention: <lang>-project-arch with references/ subdirectory.
Quality Checklist for Language Skills
Before publishing, verify your skill passes these:
