First-time setup of an AI agent

This guide takes you from an empty terminal to the first task the agent completes and verifies on its own. The main example is Claude Code, but the same steps exist in Codex and Cursor; they get a separate section at the end. All commands come from the official documentation, with links at the end of the article.

#What you need

• A git project you know well. Give the first task somewhere you will spot a mistake right away.
• A command that checks the project: tests, a build, or at least a type check.
• For Claude Code, a Pro, Max, Team or Enterprise subscription or a Console account. The free claude.ai plan does not include access to Claude Code.

#Step 1. Installation

The recommended method for macOS, Linux and WSL is the native installer. It updates itself in the background:

curl -fsSL https://claude.ai/install.sh | bash
claude --version

Alternatives are Homebrew (brew install --cask claude-code) and npm (npm install -g @anthropic-ai/claude-code, requires Node.js 22+). Homebrew and WinGet installs do not update themselves. If something is wrong, run claude doctor: it shows diagnostics for the installation and settings without opening a session.

For the first run, type claude in the project folder. The agent will open a browser for sign-in.

#Step 2. The instructions file: CLAUDE.md

Every session starts with an empty context. To keep the agent from learning the project from scratch every time, you need CLAUDE.md: a file with persistent instructions that is loaded at the start of every session.

Run /init in a session. The agent will study the code and create a file with the build and test commands and the conventions it found. If the file already exists, /init will suggest improvements rather than overwrite it.

Then edit the result. Rules from the memory documentation:

• Under 200 lines. A long file takes more context and is followed less reliably.
• Verifiable wording. “Use 2-space indentation” instead of “format neatly.” “Run npm test before committing” instead of “test your changes.”
• No contradictions. If two rules conflict, the agent may pick either one.

Example:

# CLAUDE.md
## Commands
- Tests: `npm test`
- Type check: `npx tsc --noEmit`

## Architecture
- API handlers live in `src/api/handlers/`
- Shared types are in `src/types/`

## Rules
- Don't change DB migrations without an explicit request
- New dependencies only after approval

Where else instructions live:

CLAUDE.md can import other files with a @path/to/file line, nested up to four levels deep. Imports don't save context: imported files are also loaded at startup.

#Step 3. Permissions

Permissions are set in settings.json. Levels, from highest to lowest: the organization's managed settings, command-line arguments, .claude/settings.local.json (just you, this project), .claude/settings.json (the whole team), ~/.claude/settings.json (you, all projects).

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(git push *)"]
  }
}

How it works, according to the permissions documentation:

• Rules are evaluated in order: deny, then ask, then allow. The first match wins. An allow rule cannot carve an exception out of a deny.
• The asterisk can go anywhere: Bash(npm run *) matches npm run build but not npm install.
• To keep the agent from reading secrets, you need a Read rule in deny. A .claudeignore file has no effect.

Separately from the rules, you choose a permission mode. You switch modes with Shift+Tab: default (Manual: everything except reading needs confirmation), acceptEdits, plan, auto, dontAsk, bypassPermissions. In recent versions an interactive session starts in auto by default: a separate classifier model checks the actions. For your first task in an unfamiliar project, deliberately switch to plan or Manual.

#Step 4. The first task: explore, plan, implement, commit

The recommended order from the best practices:

1. Explore. Turn on plan mode (claude --permission-mode plan or Shift+Tab until you see “plan mode on”). Ask it to read the relevant part of the code.
2. Plan. Ask for a plan of changes: which files, in what order. Ctrl+G opens the plan in your editor, where you can edit it by hand.
3. Implement. Approve the plan and ask it to implement, write tests, run them and fix the failures.
4. Commit. Review the diff and ask for a commit with a clear message.

A plan helps when the task touches several files or you don't know how to approach it. If the change fits in one sentence (“rename the variable”), you don't need a plan.

#Step 5. Verifying the result

The agent finishes when the work looks done. So every task needs a criterion it will check on its own:

The build fails with an error: [paste the error]. Find the cause, fix it,
make sure the build passes. Don't suppress the error; fix the cause.

Ask for evidence: test output, the command and its result. That is faster than re-checking yourself.

#If you use Codex or Cursor

Codex CLI is installed with npm install -g @openai/codex or brew install --cask codex and started with codex. The /init command creates AGENTS.md. Codex assembles instructions as a chain: the global ~/.codex/AGENTS.md, then files from the repository root down to the current folder, with closer ones overriding farther ones; the default limit is 32 KiB. Settings live in ~/.codex/config.toml. In Auto mode (--sandbox workspace-write --ask-for-approval on-request), Codex reads, edits and runs commands in the working folder on its own, but asks before going outside it and before accessing the network. Network access is off by default. The /permissions command switches modes, for example to read-only for discussion without edits.

Cursor stores project rules in .cursor/rules/ as .mdc files with the description, globs and alwaysApply fields. A rule can apply always, at the agent's discretion, to files matching a glob, or manually via an @-mention. A simple alternative is AGENTS.md at the root or in subfolders.

One file for all agents. Claude Code reads AGENTS.md if the project has no CLAUDE.md. If you need CLAUDE.md, import the shared file with @AGENTS.md on the first line and add Claude-specific instructions below it.

#Common mistakes

• The dumping-ground session. You start one task, get distracted by another, come back, and the context is full of noise. Run /clear between unrelated tasks.
• Endless corrections. If the agent is still wrong after two corrections, start over with /clear and a more precise prompt.
• A bloated CLAUDE.md. If the agent already does something right without an instruction, delete the instruction or replace it with a hook.

The next step is advanced setup: skills, hooks, subagents and MCP.