DEV Community

Cover image for How to structure your project folder to use, Coding Agents like Claud code, open code more efficiently
Vikrant Bagal
Vikrant Bagal

Posted on

How to structure your project folder to use, Coding Agents like Claud code, open code more efficiently

How I Structure Project Folders So Coding Agents Actually Work

TL;DR: The difference between an agent that feels like a senior teammate and one that hallucinates broken imports comes down to four things: an AGENTS.md file, progressive disclosure of context, feature-localized folder structure, and agent-specific config folders. Skip these and you'll burn tokens on re-explaining your stack every session. Adopt them and you'll cut rephrasing by 25% and framework errors by 90%.

Introduction

Six months ago, I watched a demo where someone told Claude Code to "add a user profile page" and it built the route, the component, the database migration, and the tests in one shot without being told the tech stack. I tried the same thing on my project and got back a file written in Vue when I use React, a database query against a table that doesn't exist, and a test framework I don't have installed. The difference wasn't the tool—it was the project structure.

Coding agents are only as good as the context you give them. And the most efficient way to give them context isn't to type it out each session—it's to bake it into your folder layout. Here's exactly how I do it.

Structure Project Folders So Coding Agents Actually Work

1. Start with an Agent Instruction File (AGENTS.md)

Every agent needs a persistent memory file at the project root. For OpenCode it's AGENTS.md; for Claude Code it's CLAUDE.md. This file is read automatically at session start, telling the agent your tech stack, folder conventions, build commands, and rules—so you never have to repeat yourself.

Here's the structure I use, adapted from the official Claude Code best practices:

# Project conventions
- Language: TypeScript strict
- Framework: Next.js 15 App Router
- Tests: Vitest + Testing Library
- Style: Prettier + ESLint flat config

# Code rules
- No TypeScript `any`
- Functional components only
- File names in kebab-case

# Commands
- Build: `npm run build`
- Dev: `npm run dev`
- Test single: `npx vitest run --reporter=verbose`
- Lint: `npm run lint`

# Architecture
- Components in `src/components/`
- API routes in `src/app/api/`
- Database schema in `prisma/schema.prisma`
- Shared utils in `src/lib/`
Enter fullscreen mode Exit fullscreen mode

The impact is measurable. According to the SFEIR Institute, a well-structured instruction file reduces time spent rephrasing by 25%, eliminates 90% of framework-related errors, and improves code style consistency by 70%. Those aren't marketing numbers—they're from teams that measured before and after.

⚠️ Watch the 200-line ceiling. If your AGENTS.md exceeds 200 lines, split it into imported files. Otherwise you're eating into the agent's context window before it even starts working.

2. Use Progressive Disclosure to Avoid Context Bloat

The biggest mistake I see is dumping everything into a single instruction file. Agents have a limited context window, and past 40% capacity, output quality degrades considerably—I've seen this called the "40% Rule" in practice.

Instead, structure your context in layers:

Root AGENTS.md — lightweight, points to more detailed files

# Project conventions
[tech stack, rules, commands — keep under 100 lines]

# Detailed references (load on demand)
- API patterns: `docs/guides/api-patterns.md`
- Database conventions: `docs/guides/db-conventions.md`
- Component standards: `docs/guides/components.md`
Enter fullscreen mode Exit fullscreen mode

When the agent needs to implement a feature, it reads the pointer file, then fetches only the relevant deep reference. The rest stays out of the context window.

One developer I know (Mike Bayly) had a vault-level instruction file that consumed 2,000 tokens every session—even when editing a single file. Restructuring with progressive disclosure eliminated that waste entirely.

3. Layout Code by Feature, Not by Layer

This is the structural change with the highest payoff. Instead of this:

src/
  controllers/
  services/
  models/
  routes/
Enter fullscreen mode Exit fullscreen mode

Use vertical slices:

features/
  users/
    users.controller.ts
    users.service.ts
    users.model.ts
    users.routes.ts
  billing/
    billing.controller.ts
    billing.service.ts
    billing.model.ts
    billing.routes.ts
Enter fullscreen mode Exit fullscreen mode

Why it matters for agents: When you ask an agent to "add a payment method to billing," it needs to read the billing slice. If you use layer-based structure, the agent has to read controllers/billing.ts, services/billing.ts, models/billing.ts, and routes/billing.ts from three directories away. With vertical slices, everything lives in one folder. That's fewer file reads per task, which means less token consumption and faster completions.

Tim Deschryver rewrote an entire ASP.NET API + Angular frontend using this approach with AI agents. He explicitly credits the pre-defined folder structure (Vertical Slice Architecture) as critical to success. Sid Saladi, who reviewed dozens of Claude Code projects, calls messy folder structure the top reason agents behave like "confused interns."

⚠️ Don't take this advice halfway. A hybrid structure (some features grouped, others layered) confuses agents more than a consistent layered layout. Pick one pattern and enforce it.

4. Create Agent-Specific Configuration Folders

Your main source code shouldn't be cluttered with agent configuration. Use hidden directories at the project root:

.claude/
  commands/
  skills/
  agents/
  rules/
  output-styles/
Enter fullscreen mode Exit fullscreen mode

Or for OpenCode:

.opencode/
Enter fullscreen mode Exit fullscreen mode

And for Cursor:

.cursor/
  rules/
Enter fullscreen mode Exit fullscreen mode

These folders keep agent configuration version-controlled and shareable across the team, separate from source code. I keep reusable skills there—security review prompts, SEO analysis workflows, component audit templates—that I can invoke by name during a session.

Ran Isenberg, an AWS Serverless Hero, rebuilt his entire consulting brand website using Claude Code and structured his project this way. He found that MCP servers could be replaced entirely by well-written .md skill files in .claude/skills/—more transparent and easier to audit.

5. Run /init to Bootstrap, Then Refine

Both Claude Code and OpenCode ship a /init command that scans your project's package.json, folder structure, lint configs, test frameworks, and git history, then auto-generates a starter AGENTS.md or CLAUDE.md.

Start every new project with:

/init
Enter fullscreen mode Exit fullscreen mode

Then refine the output. Delete what's irrelevant. Add your specific rules. Split long files as described above. The command gives you a 70% complete first draft, and you finish the last 30% by hand.

The Proven Template

After reviewing dozens of agent-friendly projects (including Anthropic's internal engineering teams and the community skills ecosystem), here's the layout I now reach for on every new project:

project-root/
  AGENTS.md              # < 200 lines, lightweight pointer
  src/
    features/            # vertical slices
      users/
      billing/
      notifications/
  docs/
    guides/              # deep reference files for agents
  .claude/
    skills/              # reusable skill files
    commands/
  .cursor/
    rules/               # scoped rule files for Cursor
Enter fullscreen mode Exit fullscreen mode

Over 160,000 repositories now contain a CLAUDE.md file and over 25,000 contain .cursorrules as of mid-2025. The ecosystem is converging on this pattern because it works.

What to Try Next

Stop treating your agent like a search engine that you describe your codebase to each session. Instead, treat your project structure as the permanent briefing document. Spend one hour setting up AGENTS.md, vertical slices, and .claude/ folders. Then measure how many fewer iterations you need to complete a task.

If you've already tried this, I want to know: what rule in your AGENTS.md saved you the most time? Drop it in the comments—I'm always looking for new patterns to steal.

Connect on LinkedIn: https://www.linkedin.com/in/vikrant-bagal

Infographic

Top comments (0)