How to Set Up an AI Coding Agent From Scratch
By Tyler Cyert
Setting up an AI coding agent properly takes about 30 minutes and saves hours on every project afterward. Most developers start using AI coding tools by typing prompts into a chat — but the real productivity unlock comes from configuring the agent with persistent instructions, permissions, and project structure so it produces consistent results from the first session.
This guide walks through the complete setup for Claude Code, but the principles apply to any AI coding agent including OpenCode, Cursor, and Aider.
Step 1: Create Your Instruction File
Every AI coding agent needs a persistent instruction file — a markdown document that tells the agent what your project is, how it is built, and what conventions to follow.
In Claude Code, this is CLAUDE.md. In OpenCode, it is AGENTS.md. In Cursor, it is .cursorrules or .cursor/rules/.
Your instruction file should include:
- Project description — what the project does and its current state
- Stack — languages, frameworks, databases, and major dependencies
- Build commands — how to run, build, test, and lint
- Architecture — key directories and what they contain
- Code style — naming conventions, import patterns, component structure
- Rules — things the agent must always or never do
Keep it under 200 lines. This file loads into every session, so everything in it should be universally relevant. Move file-specific conventions to scoped rules.
Step 2: Configure Permissions
AI coding agents can run shell commands, edit files, and access external services. Without explicit permissions, you either approve every action manually (slow) or trust the agent completely (risky).
The best practice: explicitly allow safe operations and explicitly deny dangerous ones.
- Allow read-only operations and specific build commands
- Deny destructive operations like
rm -rf,git push --force, and database resets - Ask for everything else (this is the default)
In Claude Code, permissions go in settings.json. See our permissions guide for ready-made patterns.
Step 3: Set Up Your Project Structure
AI coding agents work better with clear project structure. The agent needs to understand where things live and where to put new things.
At minimum:
- Source code in a consistent directory structure (
src/, with subdirectories by feature or layer) - Tests colocated with code or in a parallel
tests/directory - Configuration separated from code (
.claude/,.env.example, etc.)
For multi-agent workflows, add working directories — folders with defined purposes and INSTRUCTIONS.md files that tell agents what goes in and comes out.
Step 4: Add Automation
Set up hooks to automate repetitive tasks:
- Auto-format — run your formatter after every file change
- Test runner — run relevant tests after code edits
- Safety gates — block dangerous commands before they execute
Hooks make these behaviors deterministic. The agent cannot skip them, forget them, or decide they are not needed.
Step 5: Define Agent Roles (Optional)
If your workflow involves multiple concerns — writing code, reviewing it, writing tests, deploying — define agent roles as separate files. Each role specifies what the agent focuses on, which tools it uses, and which directories it works in.
Even if you are not using multi-agent features yet, defining roles helps you think about separation of concerns in your AI-assisted workflow.
The Setup Checklist
| Step | File | Required? | Purpose |
|---|---|---|---|
| Instruction file | CLAUDE.md or AGENTS.md | Yes | Project context and conventions |
| Permissions | settings.json | Recommended | Control what the agent can do |
| Project structure | Directory layout | Yes | Clear organization |
| Auto-format hook | settings.json hooks | Recommended | Consistent formatting |
| Test runner hook | settings.json hooks | Recommended | Catch regressions |
| Scoped rules | .claude/rules/ | Optional | File-specific conventions |
| Agent roles | .claude/agents/ | Optional | Multi-agent workflows |
| MCP servers | settings.json | Optional | External tool access |
Common Setup Mistakes
Too Much in the Instruction File
If your CLAUDE.md or AGENTS.md is over 200 lines, you are wasting context window on every session. Move file-specific rules to scoped rules and procedures to skills.
No Permissions Configuration
Running with default permissions means approving every action manually. Set up allows and denies for your common operations from day one.
No Formatting Hook
Without auto-formatting, every code change needs manual cleanup. A one-line hook running Prettier or Black after every edit solves this permanently.
Skipping the Project Description
The agent does not know what your project does unless you tell it. A two-sentence project description in your instruction file prevents the agent from making wrong assumptions about purpose, audience, and scope.
Scaffolding Your Setup with DotBox
For a deeper look at what goes into a CLAUDE.md and how the .claude/ directory is organized, see those dedicated guides.
Setting up an AI coding agent from scratch means creating markdown files, JSON configs, directory structures, and ensuring everything references everything else correctly. DotBox does it in one paste — draw your agents and skills, copy the setup prompt, and paste it into Claude Code in your project root. It writes your CLAUDE.md, the .claude/ directory structure with agents, skills and a starter settings.json, and your working directories, then tells you what it created.