Vibe Coding Project Structure — by ePipra

A reusable, drop-in project scaffold for vibe coding — building software with an AI coding agent driving most of the implementation. Works across the most common AI coding platforms (Claude Code, Cursor, GitHub Copilot, Windsurf, OpenAI Codex CLI, Aider, Continue, Zed) so you set convention once and any tool your team uses picks it up.

Public, MIT-licensed. Copy it into a new project, or drop the pieces you need into an existing one.

Why one structure for many tools

Every AI coding tool invented its own config file. Rather than maintaining N separate instruction sets, this repo:

1. Puts the shared source of truth in AGENTS.md (the emerging open convention read natively by Codex CLI, Aider, Continue, Zed, Cursor, and others).
2. Gives Claude Code its own richer setup (CLAUDE.md + .claude/) since it supports structured rules, commands, skills, sub-agents, and hooks that other tools don't.
3. Adds a thin adapter file per remaining platform that just points back to AGENTS.md so instructions never drift out of sync.

Edit AGENTS.md and CLAUDE.md for your actual project; everything else is scaffold.

Structure

Vibe-Coding-Project-Structure-by-ePipra/
├── AGENTS.md                    # universal agent instructions (Codex, Aider, Continue, Zed, Cursor fallback)
├── CLAUDE.md                    # Claude Code: project overview, stack, conventions
├── CLAUDE.local.md.example      # personal overrides template (copy to CLAUDE.local.md, gitignored)
├── .mcp.json.example            # MCP server config template (copy to .mcp.json)
├── .cursor/
│   └── rules/
│       └── project.mdc          # Cursor project rules
├── .github/
│   └── copilot-instructions.md  # GitHub Copilot custom instructions
├── .windsurfrules                # Windsurf rules
├── .claude/
│   ├── settings.json             # permissions, tool access, hooks config (template)
│   ├── rules/                    # modular topic rules, auto-loaded
│   │   ├── code-style.md
│   │   ├── testing.md
│   │   └── api-conventions.md
│   ├── commands/                 # custom slash commands
│   │   ├── review.md
│   │   └── fix-issue.md
│   ├── skills/                   # auto-triggered, on-demand instructions
│   │   └── example-skill/
│   │       └── SKILL.md
│   ├── agents/                   # specialized sub-agents
│   │   ├── code-reviewer.md
│   │   └── security-auditor.md
│   └── hooks/                    # pre/post tool-use scripts
│       └── validate-bash.sh
├── .gitignore
└── LICENSE

Quick start — use it anywhere, on any platform

Pick whichever one command matches your situation. No account, config, or install beyond git/npx needed.

New project, starting fresh (keep the folder name as-is — don't rename it):

git clone https://github.com/epipra/Vibe-Coding-Project-Structure-by-ePipra.git
cd Vibe-Coding-Project-Structure-by-ePipra && rm -rf .git && git init

New project, no git history at all (uses degit):

npx degit epipra/Vibe-Coding-Project-Structure-by-ePipra Vibe-Coding-Project-Structure-by-ePipra
cd Vibe-Coding-Project-Structure-by-ePipra

GitHub CLI (creates a new repo from the template directly):

gh repo create Vibe-Coding-Project-Structure-by-ePipra --template epipra/Vibe-Coding-Project-Structure-by-ePipra --public --clone

GitHub web UI: open the repo → green "Use this template" button → "Create a new repository".

Drop into an existing project (adds the files without touching your code):

npx degit epipra/Vibe-Coding-Project-Structure-by-ePipra /tmp/vibe-scaffold
cp -r /tmp/vibe-scaffold/. .
rm -rf /tmp/vibe-scaffold

After any of the above:

1. Fill in AGENTS.md and CLAUDE.md with your real project overview, tech stack, and commands (build/test/lint).
2. Copy .mcp.json.example → .mcp.json if you use MCP servers; copy CLAUDE.local.md.example → CLAUDE.local.md for personal notes.
3. Delete adapter files for platforms your team doesn't use (e.g. drop .windsurfrules if nobody uses Windsurf).
4. Commit. Every platform below picks up its file automatically — nothing else to configure.

Zero-config per platform

Once the files are in your project root, each tool just works — open the folder in it, no setup step:

Platform	What happens
Claude Code	Loads CLAUDE.md + .claude/ (rules, commands, skills, agents, hooks) at session start.
Cursor	Loads .cursor/rules/project.mdc automatically.
GitHub Copilot (VS Code/JetBrains)	Applies .github/copilot-instructions.md to chat/completions in this repo.
Windsurf	Loads .windsurfrules automatically.
OpenAI Codex CLI / Aider / Continue / Zed	Read AGENTS.md automatically — the open cross-tool convention.
Any other AI agent	Point it at AGENTS.md — one file, plain markdown, works anywhere.

Platform notes

File	Tool	Notes
AGENTS.md	Codex CLI, Aider, Continue, Zed, Cursor (fallback), most newer agents	Open, tool-agnostic convention. Keep this as the canonical instructions.
CLAUDE.md + .claude/	Claude Code	Loaded at session start; supports rules/commands/skills/agents/hooks for larger setups.
.cursor/rules/*.mdc	Cursor	Supports frontmatter (description, globs, alwaysApply) for scoped rules.
.github/copilot-instructions.md	GitHub Copilot	Auto-applied to Copilot Chat/completions in this repo.
.windsurfrules	Windsurf (Codeium)	Plain-text rules file at repo root.

Contributing

Public and MIT-licensed — fork it, adapt it, send a PR if you improve the cross-platform mapping.