Foundation · Class 02 of 05

Your First AI Coding Environment

In Class 01 you learned what vibe coding actually is, why the architect mindset matters, and what your job is once an agent can write code. Now you choose a tool and install it. This class is the honest comparison of the five environments that matter in 2026, the paste-ready install commands per operating system, the five-layer configuration architecture every serious Claude Code setup uses, and the seven install failures that catch beginners. By the end you have a working environment, a first CLAUDE.md, and the discipline to add only what earns its place.

LevelBeginner
Read Time70 minutes
PrerequisitesFoundation 01
CostFree · no signup
PublishedMay 28, 2026

What You'll Learn

  • How to choose an environment instead of collecting tools
  • Claude Code, Antigravity, Cursor, Windsurf, and Ollama compared honestly
  • Paste-ready install commands for every OS
  • The five-layer Claude Code configuration architecture
  • How to write your first CLAUDE.md (template included)
  • MCP servers, AGENTS.md, and the Toolchain First principle
Quick Answer

Your first AI coding environment in 2026 is one of five: Claude Code (terminal-native agent, free with a Claude subscription or pay-as-you-go), Google Antigravity (free visual multi-agent IDE), Cursor or Windsurf (paid VS Code-based IDEs at $15–$20 per month), or Ollama for local sovereign models. The right starting move is Claude Code paired with one local Ollama model, configured with a single CLAUDE.md file and one MCP server. Install one tool, use it for two weeks, then add the next.

Section 01

Tools Are a Decision, Not a Collection

The first instinct of a new vibe coder is to install everything. Claude Code, Cursor, Windsurf, Antigravity, Cody, Aider, Continue, plus three local model runners and four MCP servers, all in the first weekend. Six weeks later, none of them have produced a real project, the configuration files contradict each other, and the architect blames the tools.

An architect approaches the tooling decision the same way they approach any other design decision: by naming the constraint first. Cost matters or it does not. Sovereignty matters or it does not. Speed of iteration matters or it does not. Depth of agentic capability matters or it does not. Once you have answered those four questions honestly for your work, the choice is almost mechanical.

The Four Questions Before Installing Anything

Cost: what monthly budget can you defend, and what is the marginal cost of a heavy day? Sovereignty: can your code legally and ethically leave your machine? Speed: are you iterating in seconds or minutes, and where does latency hurt the most? Depth: do you need an agent that opens twenty files, runs the test suite, and submits a pull request, or do you need a smart autocomplete? Different honest answers point to different tools.

The cost of installing the wrong tool is not the install. It is the six weeks of habit you build into a workflow you will have to unlearn. The mindset shift is to choose one environment for the next two weeks, master its behavior, then add a second only when your work outgrows the first. The tools are not the skill. The skill is the discipline of the architect inside them.

Section 01 of 12

Section 02

The Four Real Choices (Five Tools)

Out of the dozens of AI coding tools shipped in 2026, five matter for a beginner architect. They cluster into four archetypes, and which archetype you pick is more important than which specific tool inside the archetype.

Archetype 1: Terminal-native agent — Claude Code

Anthropic's Claude Code lives in your terminal, reads your files, runs shell commands, and integrates with whatever editor you already use. Its strength is depth of configuration: the five-layer architecture of CLAUDE.md, rules, skills, hooks, MCP servers, and subagents gives you levers nothing else exposes this cleanly. Its honest weakness is that there is no visual UI, so if you have never used a terminal, the first hour is friction. The pricing model is the cleanest in the market: free with a Claude Pro or Max subscription you may already pay for, or pay-as-you-go with an API key.

Archetype 2: Visual multi-agent IDE — Google Antigravity

Antigravity is Google's free agentic IDE, available at antigravity.google with a Google account. It ships with Gemini 3.1 Pro and 3.5 Flash and a 2-million-token context window. The Manager view lets you watch and steer multiple agents working in parallel from one screen, which is a genuinely new affordance. You can bring your own API key for Claude Sonnet, Opus, or GPT-OSS 120B if you prefer those models. The catch is Google account dependency — whatever happens to your Google account happens to your access — and the IDE itself is newer than Cursor or Windsurf so the rough edges show.

Archetype 3: VS Code-based AI IDE — Cursor or Windsurf

Cursor is the market leader, used by roughly a million developers and about half of the Fortune 500 as of early 2026, valued at $29.3 billion. Its Composer 2 mode rewrites across multiple files in one pass, Cursor Tab predicts where your cursor moves next, and Background Agents run tasks autonomously in the cloud. Pricing is $20 for Pro with unlimited Auto-mode usage and a metered credit pool for manually-pinned premium models, $60 for Pro+ which triples that pool, and a free Hobby tier.

Windsurf is Cursor's closest competitor, owned by Cognition (the Devin team) since their December 2025 acquisition for about $250 million. Its Cascade agent uses the proprietary SWE-1.5 model, which is roughly 13 times faster than Sonnet 4.5 on code-edit tasks. Fast Context retrieves relevant code about 10 times faster than standard agentic search. Memories persistently remember architectural decisions across sessions, which is unique. Pricing is $15 individual, $30 per team seat. Windsurf is the gentler learning curve; Cursor is the broader feature surface.

Archetype 4: Local sovereign models — Ollama

Ollama runs open-weight models on your own hardware. It is free, it works offline, your code never leaves your machine, and there are no rate limits. The price is that local frontier-quality is roughly a year behind the best cloud models, and speed depends on your GPU. With a recent NVIDIA card and at least 16 GB of system RAM, an 8B parameter model runs at usable speeds for everyday work. The DDS production stack uses Ollama for routine work and Claude Code for hard problems.

What about GitHub Copilot, Cody, Aider, Continue?

They are real tools used by real teams, and we are not naming the full universe to dismiss them. They are not the right first environment in 2026 because their agentic capability is a generation behind the five above, or their best mode requires you to already know what you are doing. Come back to them once you have shipped something with one of the five.

Section 02 of 12

Section 03

The Decision Matrix (Read This Before You Install Anything)

Pick the row that best describes your situation, then the column gives you the tool. If two rows describe you, use the higher one. This matrix does not capture everything, but it gets the first install right roughly nine times out of ten.

If your top constraint is… Start with Add second Avoid first
Lowest cost, free signupAntigravityOllamaCursor Pro
Code never leaves my machineOllamaClaude Code (with self-host carve-out)Any cloud-only tool
Deepest agent capabilityClaude CodeAntigravity Manager viewPlain Copilot
Familiar with VS Code alreadyCursor or WindsurfClaude Code in the terminalTerminal-only setups
Total beginner, gentle onboardingWindsurfClaude Code once comfortableRaw Ollama with a CLI
JetBrains / Vim / Xcode userWindsurf (plugin) or Claude CodeCursor only if you can switch editorsCursor as a daily driver
High volume of iteration dailyCursor Pro+ or Claude CodeLocal Ollama for the cheap iterationsPay-per-request without monitoring
Building agentic systemsClaude CodeAntigravity Manager viewPlain autocomplete tools

Notice what the matrix does not say. It does not say "best." It says "fits your constraint." A team of fifty enterprise developers with a six-figure tooling budget will rationally choose differently from a solo founder iterating on a side project at midnight. The architect's question is never which tool is best in the abstract. It is which tool fits the work and the constraint, today.

The DDS default answer

If you are reading this Academy with no further context about your situation, the safest first install in 2026 is Claude Code for primary work plus Ollama with the qwen3:8b model for cheap local iterations and offline runs. That is the stack this Academy was built with. We will explain exactly how to install both in Section 05.

Section 03 of 12

Section 04

The Local Path: Why Ollama Belongs in Your Stack

Local models occupy a category most beginner-focused content skips, and that is a mistake. A local Ollama install does three things no cloud tool can: it removes the per-request cost from your iteration loop, it keeps proprietary or sensitive code on your machine, and it works when the internet is down. None of those matter on day one. All three start mattering by month three.

The objection most beginners raise is "but won't local models be worse?" Yes, somewhat. A well-quantized 14-billion-parameter open-weight model in 2026 reaches roughly 85 to 90 percent of the code-task quality of a frontier cloud model on routine work, and falls further behind on hard problems. For drafting boilerplate, explaining unfamiliar code, generating tests, and the ten daily questions where you would otherwise burn API credits, that gap is acceptable and the speed and cost wins are not. For the genuinely hard problems where the last 10 percent matters, you have Claude Code or Antigravity in the same workflow.

The VRAM ladder (read carefully before you pull a model)

Ollama models come in different sizes, and the size determines what hardware can run them at usable speed. The numbers below are for the standard Q4_K_M quantization, which is the default for most Ollama models and a sensible balance of quality and footprint.

Model sizeVRAM at Q4System RAM floorWhat it's good for
7–8B~6 GB16 GBDaily coding chat, boilerplate, explanations. The starter.
13–14B~10 GB16 GBReal code generation. The default for a 12GB GPU.
32B~20–22 GB32 GBProduction-quality on most tasks. Needs a 24GB card.
70B~43 GB64 GBFrontier-adjacent. Multi-GPU or aggressive quantization.

If you do not know your GPU's VRAM, run nvidia-smi on Linux or open Task Manager → Performance → GPU on Windows. On a Mac with Apple Silicon, the unified memory architecture means your system RAM is your VRAM ceiling, and the practical floor is a 16 GB M-series machine for an 8B model.

The starter model: qwen3:8b

For your first local model, run Alibaba's Qwen 3 8B. It is fast, current, strong at code, and works on a modest GPU. The pull command after installing Ollama is below. The first pull downloads about 5 GB and takes a few minutes on a normal connection; subsequent uses are instant.

terminal — first local model Bash · Ollama
# Pull the starter model (downloads about 5 GB once)
ollama pull qwen3:8b

# Run it interactively
ollama run qwen3:8b

# Or call it from any code via the OpenAI-compatible API
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:8b",
    "messages": [{"role": "user", "content": "Write a Python function to reverse a linked list."}]
  }'

Notice the third command. Ollama exposes an OpenAI-compatible API on localhost:11434, which means anything that speaks the OpenAI API speaks Ollama with a base-URL change. That is the bridge that lets you wire Ollama into Cursor's BYO-model option, into the Continue or Cody extension, into your own scripts, and into Antigravity as a custom endpoint. The local model is not a silo. It is a drop-in for the cloud whenever you want it to be.

Section 04 of 12

Section 05

Install Walkthrough (Paste-Ready)

Each block below is a complete install for one tool on one platform. Copy the block, paste it into your terminal (or follow the GUI step where noted), wait for it to finish, and move to Section 06 to verify the install actually worked.

Claude Code — native installer (recommended)

terminal — claude code install Bash / PowerShell
# macOS or Linux (one line)
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell, one line)
irm https://claude.ai/install.ps1 | iex

# Alternative: macOS via Homebrew
brew install --cask claude-code

# Alternative: Windows via WinGet
winget install Anthropic.ClaudeCode

The first time you run claude in a project directory, it triggers an OAuth flow that signs you in with your Claude Pro or Max subscription. If you do not have a subscription, set ANTHROPIC_API_KEY in your shell environment to a key from console.anthropic.com and the same launch uses pay-as-you-go billing instead. The legacy npm install -g @anthropic-ai/claude-code still works but is deprecated in favor of the native installer.

Google Antigravity — GUI install

There is no command line for Antigravity. Visit antigravity.google in a desktop browser, click Download, and pick your platform (Mac, Windows, Linux). The installer is a standard app installer. On first launch you sign in with a Google account; the IDE is functional within thirty seconds.

Cursor — GUI install

Visit cursor.com, download the installer for your platform, and run it. On first launch Cursor offers to import your VS Code extensions, themes, and keybindings; accept this and your editor configuration carries over. Free Hobby tier requires no account; Pro at $20 a month does.

Windsurf — GUI install

Visit windsurf.com, download, and run the installer. Sign in (free tier available). The Cascade panel opens by default on the right side of the window; that is the agent surface for the entire IDE.

Ollama — local model runner

terminal — ollama install Bash / Installer
# macOS or Linux (one line)
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# Download the installer from ollama.com/download/windows and run it.

# Confirm the server is running (background service on port 11434)
curl http://localhost:11434/api/version

# Pull your first model
ollama pull qwen3:8b

On Linux, Ollama installs a systemd service that starts the server in the background. On macOS, it installs a menubar app. On Windows, it runs as a Windows service. The server listens on port 11434 by default, and that is the address your tools will use to talk to it.

Do not pipe install scripts you have not read

The one-liners above pipe a downloaded script directly into a shell. That is the official install path published by Anthropic and Ollama, and the script is short enough to read first. If you are uncomfortable with the pattern, visit the canonical URL in a browser, read the script, and only then run it. The architect mindset applies to install commands too.

Section 05 of 12

Section 06

First-Run Verification (Confirm It Works)

An install that "completed successfully" but does not actually work is the most common source of beginner frustration. Run the verification below for whichever tool you installed. If the verification fails, jump to Section 11 for the seven common failures.

Verify Claude Code

terminal — claude code verify Bash
# Step 1: confirm the binary is in PATH
claude --version

# Step 2: make a tiny project and launch
mkdir hello-claude && cd hello-claude
echo "# Hello Project" > README.md
claude

# Inside the Claude session, type:
#   Read README.md and tell me what this project is.
# You should see Claude open the file, read it, and respond.
# Exit with Ctrl+C.

If Step 1 prints a version number and Step 2 enters an interactive session where Claude can read the file, the install works. The first launch will also trigger the OAuth flow or prompt for your API key depending on how you authenticated.

Verify Antigravity

Launch the Antigravity app. Open any folder via File → Open. In the chat panel on the right, type "Read the files in this folder and tell me what is here." Antigravity should list the files and describe them. If you see the Manager view as a separate tab, click it — that is where you can spawn and orchestrate multiple agents in parallel. The Manager view is the feature that distinguishes Antigravity from Cursor and Windsurf.

Verify Cursor or Windsurf

Open any project folder. Use Cmd+L (Mac) or Ctrl+L (Windows / Linux) to open the chat panel in Cursor, or look for the Cascade panel on the right in Windsurf. Ask "What does this project do?" The agent should index the codebase and answer. For Cursor specifically, also try Cmd+I to open Composer and ask it to make a small multi-file edit; that exercises the agentic mode you actually paid for.

Verify Ollama

terminal — ollama verify Bash
# Step 1: confirm server is reachable
curl http://localhost:11434/api/version

# Step 2: list installed models
ollama list

# Step 3: run a real prompt against the starter model
ollama run qwen3:8b "Write a Python function that returns the Fibonacci sequence up to n. Include a docstring."

# You should see code stream back within a couple of seconds on most hardware.

If Step 3 streams a complete Python function with a docstring, your local environment works end-to-end. Hold onto that model name; you will use it as the default model in your shell aliases later.

Section 06 of 12

Section 07

The Five-Layer Configuration Architecture

This section is what separates a Claude Code user from a Claude Code architect. The useful Claude Code setup has five layers, each solving a different problem. They sound like five flavors of "agent customization." They are not. They are five distinct mechanisms with five different lifetimes and load behaviors. Understanding which goes where is the single configuration insight that pays back for years.

Layer 1: Project memory — CLAUDE.md

A markdown file at the project root that Claude Code reads at every session start. The file describes how your project's world works: where files live, what the naming rules are, which commands to run for build and test, what to never touch. The discipline is to keep CLAUDE.md under 200 lines. Bigger files mean lower signal-to-noise, and the model starts ignoring the middle. Stable rules go here; transient ones do not.

Layer 2: Path-scoped rules — .claude/rules/*.md

Short markdown files under .claude/rules/ that load conditionally based on which files Claude is currently working with. One file for testing conventions, one for retrieval logic, one for python typing standards. Each rule is path-scoped via a frontmatter paths: glob, so only the relevant rules load when Claude touches the relevant files. This is the layer that prevents the CLAUDE.md bloat trap. If a rule applies only to one directory, it does not belong in CLAUDE.md.

Layer 3: Reusable workflows — Skills (.claude/skills/<name>/SKILL.md)

A Skill is a markdown file with YAML frontmatter that Claude Code auto-discovers and progressively loads only when relevant. Skills encode workflows you have repeated more than twice: a deployment checklist, a docs-refresh procedure, a code-review methodology, a debugging playbook. The Skills format shipped in October 2025 and the open spec landed in March 2026; expect more tools to support it. The architect's rule is simple: any procedure you have done twice deserves a SKILL.md so the third time is the agent's job.

Layer 4: Deterministic guardrails — Hooks

Hooks are user-defined scripts that fire on specific lifecycle events: PreToolUse (before Claude runs a tool), PostToolUse (after), UserPromptSubmit (when you send a message). Hooks run outside the agent loop and are deterministic, which makes them the right place for guardrails. "Block any write outside the src/ directory." "Run the test suite after every file edit and abort if it fails." Unlike CLAUDE.md instructions which are advisory and can be ignored, hooks are enforced. Use hooks for anything that must happen every time with zero exceptions.

Layer 5: External tools — MCP servers and subagents

MCP servers connect Claude Code to systems outside its default environment: GitHub for pull-request operations, your filesystem for direct file access, a database for queries, Slack for team comms, Figma for design assets. We cover MCP setup in Section 09. Subagents are isolated contexts spawned for specific work; each gets its own tools, permissions, and memory. The pattern is to delegate research-heavy or review-heavy work to a subagent so the main session stays clean.

The five layers, mapped to the file system

A mature Claude Code project layout looks like this: CLAUDE.md at the root for the under-200-line project memory; .claude/rules/*.md for path-scoped rules; .claude/skills/<name>/SKILL.md for each reusable workflow; .claude/settings.json for hook definitions; .mcp.json for MCP server configuration. None of these is long. Each does one thing well. The architecture is a separation of concerns problem, and the layers are the concerns.

Section 07 of 12

Section 08

Your First CLAUDE.md (Paste-Ready Template)

This template is the canonical starting CLAUDE.md. It is intentionally minimal so it fits well under 200 lines, and every section earns its token cost. Copy it into the root of your project, rename the placeholders, delete any section that does not apply, and you have a working project memory in five minutes.

CLAUDE.md Markdown · Project Memory
# Project: {{ project_name }}

## What this project is
One sentence about what this codebase does and who it is for.

## Architecture in five bullets
- Stack: {{ language }} {{ framework }} ({{ runtime_version }}).
- Entry point: src/main.{{ ext }} (or path equivalent).
- Data layer: {{ database }} accessed through {{ orm }}.
- Tests: {{ test_framework }} under tests/.
- Deploys: {{ deploy_target }} via {{ deploy_command }}.

## File conventions
- Source files live under src/. Tests mirror the structure under tests/.
- One exported component per file, named after the file.
- Imports ordered: stdlib, third-party, local. Sorted alphabetically inside groups.

## Commands you should use, not invent
- Install: {{ install_command }}
- Run dev: {{ dev_command }}
- Run tests: {{ test_command }}
- Lint: {{ lint_command }}
- Format: {{ format_command }}
- Build: {{ build_command }}

## Never do this
- Never edit files under generated/ or dist/. They are produced by the build.
- Never commit anything matching .env*. Secrets live in {{ secret_manager }}.
- Never bypass the linter; if a rule is wrong, change the rule, not the code.
- Never write to the database directly; always go through the data layer.

## When in doubt
- Prefer reading existing code over inventing a new pattern.
- Ask before adding a new top-level dependency.
- If a task is ambiguous, propose the smallest version first and confirm.

## Definition of done
- Code passes lint, type-check, and tests locally.
- New behavior is covered by at least one test.
- User-facing strings are pulled from {{ i18n_or_strings_file }} when applicable.

Read what is not in this template. There is no "be helpful." There is no "use best practices." There is no "explain your reasoning." All three are noise. The model already knows to be helpful, what best practices look like, and when to explain. What it does not know is where your tests live, which command produces a clean build on your machine, and that nobody on your team is allowed to edit the generated/ directory. That is what CLAUDE.md is for.

The placeholder pattern {{ project_name }}, {{ database }}, and so on is so that you can fill in once and have a real working file. Replace each placeholder with your concrete value, delete the sections that do not apply (no database? delete that line), and commit the result to your repo. Future-you on a new machine and any teammate who clones the repo immediately has a project-aware agent.

When the template feels too short, that is the point

The first instinct is to expand: add an "About me" section, paste your architecture diagrams, write three paragraphs on coding style. Resist. Every token in CLAUDE.md is loaded into every session, which means every token competes with the actual work for the model's attention. The 200-line limit is not arbitrary; it is the empirical ceiling beyond which agents start ignoring the middle. Shorter and sharper outperforms longer and gentler.

Section 08 of 12

Section 09

MCP in One Lesson

The Model Context Protocol is a small open standard that lets an AI agent talk to external tools and data sources. Without MCP, every agent has to ship a custom integration for every tool. With MCP, you install one server — say, GitHub — and every MCP-compatible agent on your machine immediately has GitHub operations available: issues, pull requests, repo search, code review. The protocol is the integration; the server is the implementation. That is the whole pitch.

Two transports, three scopes

MCP servers run in one of two transports. Local stdio servers are small processes Claude Code launches on demand; they talk over standard input/output. Filesystem, Playwright, and Postgres servers are usually local stdio. Remote HTTP/SSE servers are hosted, authenticate via browser, and are reached by URL. Sentry, Linear, Figma, Supabase, and Notion all ship official HTTP-transport servers as of 2026.

Each server is configured at one of three scopes: local (just this machine), project (committed to .mcp.json in the repo), or user (your home directory, available everywhere). Project scope is the right default for anything teammates will share; local is right for personal tooling; user is right for cross-project conveniences like GitHub.

The 2026 inflection: Tool Search

Until early 2026, every connected MCP server's tool definitions loaded into the model's context at session start. That capped practical setups at three or four servers before the noise started degrading performance. In 2026, Claude Code introduced Tool Search: tool definitions are discovered on demand, not loaded preemptively. The practical ceiling moved upward, but a soft ceiling still exists. Past roughly 50 visible tools the model starts choosing the wrong one because the selection task gets noisier with each option. Start with two or three servers. Add only when a workflow needs it.

Your first .mcp.json

.mcp.json JSON · Project-scoped MCP config
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/path/to/this/project"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

Drop this file at the root of a project, fill in the absolute path and your GITHUB_TOKEN environment variable, and Claude Code will load both servers when you launch a session in that directory. The filesystem server gives Claude scoped read/write to the project; the GitHub server gives it issue and pull-request operations.

Keep secrets out of project-scoped configs

Most teams commit .mcp.json to the repo so everyone shares the same servers. That means any inline token in the file leaks the moment the repo is shared. Use the ${ENV_VAR} reference pattern shown above so the actual token lives in your shell or a local .envrc that is gitignored. Also: when you add a new server, restart Claude Code completely. The config is read at startup and changes are ignored until you reload.

The first three servers worth installing

Filesystem for scoped read/write to your project. GitHub for issues, pull requests, and code search. Playwright if you do any web work, because being able to ask the agent to "open this URL and tell me what is on the page" closes the loop on testing UI changes. Three servers gets you 80 percent of the practical leverage. Add the fourth when you have a specific workflow that needs it, not before.

Section 09 of 12

Section 10

AGENTS.md and the Toolchain First Principle

AGENTS.md is the open standard that the AI coding tool ecosystem converged on for cross-tool project guidance. It is a plain Markdown file at the repository root that tells any AI coding agent how to build, test, and contribute to the project. It is stewarded by the Linux Foundation's Agentic AI Foundation, has been adopted by more than 60,000 repositories, and is read natively by Cursor, Codex, GitHub Copilot, Gemini CLI, Aider, Windsurf, Zed, Factory, Jules, and over twenty other tools. Think of it as a README for agents.

The pattern that has emerged in 2026 is: AGENTS.md as the universal source of truth, with tool-specific files (CLAUDE.md, .cursorrules, copilot-instructions.md) importing from it where needed. That way one canonical document drives every agent on the team, and the tool-specific files only carry the rules that are genuinely tool-specific.

The empirical finding nobody talks about

Here is the catch. Academic research from 2026, including a paper at ICSE JAWs 2026, studied 138 real-world repositories and found that LLM-generated context files (the kind a tool offers to write for you) reduce agent task success while inflating inference cost by over 20 percent. Developer-written context files provided only a marginal improvement of about 4 percent, and only when they were minimal and precise.

The mechanism is not that agents ignore the instructions. The opposite: agents follow them faithfully, which broadens exploration and increases reasoning cost without improving outcomes. Unnecessary requirements actively harm agent performance, not help it. This is one of the most important and least-known results in the field, and it shapes the principle below.

The Toolchain First Principle

If a constraint can be enforced deterministically by a tool already in the repo — a linter, a formatter, a type checker, a hook, or a CI gate — it must not be restated in AGENTS.md or CLAUDE.md. The tool is the constraint. Restating it in prose costs tokens, broadens the agent's exploration, and slows it down without any improvement in outcomes. Reserve AGENTS.md for the things you cannot encode in tooling: the project's purpose, the architectural constraints that have no linter, the things you tried that did not work, the things to never do that no automated check catches.

A minimal AGENTS.md

AGENTS.md Markdown · Universal Agent Memory
# AGENTS.md

> Project: {{ one-line description of what this codebase does }}.
> Core constraint: {{ the non-negotiable that shapes every decision }}.

## How to work in this repo

- Build: {{ build_command }}
- Test: {{ test_command }} (must pass before any PR)
- Lint and format: {{ lint_command }} (the linter is the style guide)
- Type check: {{ typecheck_command }}

## Architectural decisions agents must respect

- {{ Architectural rule 1 that no linter catches. }}
- {{ Architectural rule 2 that no linter catches. }}

## What we have already tried that did not work

- {{ Failed approach 1, why we abandoned it. }}
- {{ Failed approach 2, why we abandoned it. }}

## Out of scope

- {{ Things this codebase deliberately does not do, so agents do not invent them. }}

Notice what is not here. No "follow our style guide" (the linter enforces it). No "write tests" (the CI gate enforces it). No "use TypeScript types" (the type-check command enforces it). Every line that survives passes the Toolchain First test: it is something no automated tool in the repo can enforce. That is what makes AGENTS.md earn its tokens.

Section 10 of 12

Section 11

The Seven Install Failures That Catch Beginners

Every single one of these has cost someone a Saturday. The fix in each case is a one-liner once you know what is happening; the lost time comes from not knowing. Skim the list now and reread it the moment something does not work.

1. claude: command not found after install

The native installer placed the binary in a directory not on your PATH. On macOS and Linux the install path is usually ~/.local/bin or /usr/local/bin. On Windows it is %LOCALAPPDATA%\Programs\Claude. Either add that directory to PATH in your shell config, or open a fresh terminal — the installer often updates PATH in your shell config file and the change does not take effect until a new shell session.

2. OAuth callback blocked by corporate proxy or VPN

Claude Code's first-launch OAuth flow opens a browser window that posts back to a localhost callback. Corporate VPNs and proxies that intercept localhost traffic break this. The workaround is to set ANTHROPIC_API_KEY directly and skip the OAuth entirely; pay-as-you-go works without the callback. The longer-term fix is whitelisting the callback in your proxy config.

3. Ollama "out of memory" on the first big model pull

You pulled llama3.3:70b on a machine with 16 GB of RAM. The model loads but inference fails the moment you give it a prompt. Look at the VRAM ladder in Section 04 before you pull anything past 14B. The fix is to delete the model (ollama rm llama3.3:70b) and pull one that fits your hardware. For most beginner setups that means qwen3:8b or qwen3:14b.

4. Ollama installs but localhost:11434 returns nothing

The Ollama server is not running. On Linux: sudo systemctl start ollama. On Mac: open the Ollama menubar app. On Windows: open Services and start the Ollama Server service, or restart the machine and let the service start on boot.

5. Cursor or Windsurf cannot find your VS Code extensions

The import-from-VS-Code step on first launch found a different VS Code installation than you expected, usually because you have both stable and Insiders builds. Fix: in Cursor or Windsurf, run the command "Import VS Code Settings" from the command palette and pick the right source. Most extensions install in a few seconds.

6. Antigravity hangs on first Google sign-in

The Google sign-in opens a browser window for OAuth; if your default browser has aggressive privacy extensions (uBlock Origin with strict mode, Privacy Badger, etc.) the OAuth redirect can fail silently. Fix: temporarily disable extensions on the OAuth tab, or use a different browser as the system default during sign-in.

7. .mcp.json changes ignored

You edited the file but Claude Code still does not know about the new server. The MCP config is read at session startup, not on file change. Close the Claude session completely (Ctrl+C twice in the terminal), then relaunch. Same applies to any change in CLAUDE.md, .claude/rules/, or .claude/skills/ — restart the session to reload.

Section 11 of 12

Section 12

The DDS Recommended Path (Five Days)

If you started this class with no AI coding tools installed and want a concrete plan for the next week, here it is. Each day's work takes one hour of focus or less. By Friday you have a working environment, a real project memory file, one MCP server, one Skill, and a universal AGENTS.md. That is more configuration discipline than most professional developers have.

Day 1. Install Claude Code via the native installer. Authenticate with whichever credential you have. Run the Section 06 verification. Touch nothing else.

Day 2. Install Ollama. Pull qwen3:8b. Run a real prompt against it from the terminal. Confirm the OpenAI-compatible API on localhost:11434 responds.

Day 3. Open a real project (any size). Drop the Section 08 CLAUDE.md template at the root. Replace every placeholder with your real value. Delete sections that do not apply. Commit it.

Day 4. Drop the Section 09 .mcp.json at the project root with the filesystem server only. Restart Claude Code. Confirm it works. Resist installing more servers.

Day 5. Find one workflow you have already done twice this week — a deploy, a doc refresh, a test-writing pattern — and write a SKILL.md for it under .claude/skills/<name>/. Run Claude Code on the third occurrence and watch it use the skill.

Week two: add AGENTS.md if you collaborate with others or use multiple AI tools. Week three: add a second MCP server only when a real workflow demands it. Month two: revisit your CLAUDE.md and ruthlessly cut anything the linter or CI gate already enforces. That is the discipline.

What this Academy was built with

Every page in this Academy, including the one you are reading, was built with Claude Code as the primary agent, paired with a local Ollama model for cheap iterations, configured through a CLAUDE.md tuned to under 200 lines, one filesystem MCP server, and one Skill called shopify-dds-mastery that encodes the entire Shopify Liquid + SEO Magnet workflow. No Cursor, no Windsurf in the production loop. The same stack we are recommending is the stack that built the recommendation.

You now have the environment, the configuration architecture, and the discipline to add only what earns its place. The next class — Foundation 03 — takes the tool you can run and teaches you how to write the prompts that turn it into software you can ship. The skill is not in the typing. It is in the specifying.

Section 12 of 12 · Foundation Class 02 Complete

Look What You Can Make

Built with the exact stack this class recommends

Every example below was built by an architect using Claude Code with a CLAUDE.md and one Skill. No Cursor. No Windsurf. Same five-layer architecture you just learned.

Robert McCullock

Architect-CEO · Design Delight Studio

Boston-based. Built a sustainable-streetwear brand and a portfolio of AI systems using the intent-based engineering method taught in this Academy. Daily-driver stack: Claude Code + Ollama + one MCP server, exactly as recommended in Section 12.

FAQ

Frequently Asked Questions

The questions newcomers ask most about setting up their first AI coding environment. Each answer matches this page's structured data exactly, so a person reading the page and an AI engine extracting the schema receive the same canonical response.

Which AI coding tool should I start with in 2026?

If you want one recommendation: Claude Code. It is free to install, runs in your terminal so it works alongside any editor you already use, and the five-layer configuration architecture (CLAUDE.md, rules, skills, hooks, MCP servers, subagents) is the most portable knowledge in the field. The second recommendation is Google Antigravity, which is also free and gives you a visual Manager view for multi-agent work. Install one. Use it for two weeks before considering another.

Do I need a paid subscription to start AI coding?

No. Claude Code can be used with a Claude.ai Pro/Max subscription if you already pay for one, but it also accepts an API key with pay-as-you-go billing. Google Antigravity is free at antigravity.google. Ollama is free and runs models locally on your hardware. Cursor and Windsurf both have free tiers as well. You can build real software for under $20 a month, and you can build prototypes for free.

What hardware do I need to run AI coding tools?

For cloud-based tools (Claude Code, Antigravity, Cursor, Windsurf) you only need a modern laptop with a working internet connection. For local models with Ollama the floor is 16 GB of system RAM for an 8B-parameter model, and an NVIDIA GPU with 8 GB or more of VRAM is strongly recommended for usable speed. A 14B model wants around 10 GB of VRAM; a 32B model wants 20 to 22 GB; a 70B model wants roughly 43 GB at the standard Q4 quantization.

Is Cursor better than Claude Code?

They solve different problems. Cursor is a full VS Code-based IDE built around an AI agent, with multi-file Composer edits, predictive Cursor Tab completions, and cloud Background Agents. It is best when you want everything in one window. Claude Code is a terminal-native agent that integrates with whatever editor you already use, with deeper configuration (skills, hooks, subagents) and clearer cost control. Cursor charges $20 per month for Pro plus a metered credit pool; Claude Code is free with a Claude subscription or pay-as-you-go via the API. Pick by where you work, not by which is fashionable.

Can I use multiple AI coding tools at once?

Yes, and most professional architects do, but only after they have mastered one. A common DDS-recommended stack is Claude Code for daily work plus Ollama for local sovereignty and offline runs. Some teams add Cursor or Windsurf when their work is heavily IDE-centric. The mistake is installing four tools on day one. The mindset travels across tools; the tools do not teach the mindset. Learn one until you can predict what it will do, then add a second.

What is the difference between Cursor and Windsurf?

Both are VS Code-based AI-native IDEs. Cursor is the market leader with about one million active users as of early 2026 and a $29.3 billion valuation; its flagship feature is Composer 2 multi-file editing plus cloud Background Agents. Windsurf was acquired by Cognition AI (makers of Devin) in December 2025 for about $250 million; its flagship is Cascade with proprietary SWE-1.5 (about 13 times faster than Sonnet 4.5 for code) and the Memories long-term architectural memory feature. Cursor's edge is the broader feature surface; Windsurf's edge is the agent speed and beginner-friendlier flow.

Why would I run a model locally with Ollama?

Three reasons. Sovereignty: your code never leaves your machine, which matters for proprietary work, sensitive prompts, or regulated industries. Cost: after the hardware is bought you pay nothing per request, which adds up when you are iterating heavily. Resilience: you can work offline, you do not depend on a vendor's uptime, and you cannot be rate-limited. The trade-off is that local frontier-quality is roughly a year behind the best cloud models, and speed depends on your GPU. Most DDS work pairs Claude Code for hard problems with a local Ollama model for everything else.

What is MCP and do I need it?

MCP is the Model Context Protocol, an open standard for how AI agents talk to external tools and data sources. With MCP, you install one server (say, GitHub) and every MCP-compatible agent on your machine immediately gets the GitHub operations as tools. Without MCP, every tool ships its own bespoke integration for every agent. You do not need MCP on day one. You will want it as soon as you have a workflow that touches an external system more than a few times, which usually means GitHub, your filesystem, or a database. Add one server, use it for a week, then add the next.

What should I put in CLAUDE.md?

Project conventions that the AI cannot infer from the code. Where files live, what the naming rules are, what to never touch, which commands to use for build/test/lint, what the user-facing language is. Keep it under 200 lines. The mistake new architects make is treating CLAUDE.md as a personality file ("be helpful, be concise"); models already know that. CLAUDE.md is a how-our-world-works file. The paste-ready template in this class shows the seven sections that earn their token cost.

Should I use AGENTS.md or CLAUDE.md?

Both, in different roles. AGENTS.md is the open universal standard adopted by over 60,000 repositories and natively supported by Cursor, Codex, Copilot, Gemini CLI, Aider, Windsurf, Zed, and others. CLAUDE.md is the Claude Code-specific extension where you put rules only Claude Code understands (skills directives, hook references, MCP-scoped instructions). A common pattern is to keep AGENTS.md as the source of truth and import it from CLAUDE.md so the universal context lives in one place.

What is a Skill in Claude Code?

A Skill is a markdown file at .claude/skills/<name>/SKILL.md with YAML frontmatter that Claude Code auto-discovers and loads only when relevant. Skills encode reusable workflows: a docs refresh skill, a deployment checklist, a debugging playbook, a code review methodology. The model uses its existing capabilities (file reading, terminal commands) to follow your skill's instructions. The Skill spec is open as of March 2026. Start by writing a SKILL.md for the first workflow you have already done twice.

Are Cursor's credits a hidden cost?

Not hidden, but easy to misread. The $20 Pro plan includes unlimited usage on Auto mode, where Cursor picks a model for you. When you manually pin a premium model like Claude Opus 4.7, that request draws from a dollar-denominated credit pool. Heavy manual users can burn $20 in credits within a couple of weeks. The fix is to stay on Auto unless you have a clear reason to override, and to check Settings to Billing for the real-time meter. Pro+ at $60 per month triples the credit pool for sprint-heavy work.

Is Google Antigravity actually free?

Yes, as of May 2026. Download at antigravity.google, sign in with a Google account, and you have Gemini 3.1 Pro and 3.5 Flash with a 2-million-token context window at no cost. The Manager view lets you orchestrate multiple agents in parallel from one UI. You can also bring your own API key for Claude Sonnet, Opus, or GPT-OSS 120B. The catch is Google account dependency: anything Google does to your account affects your access. Many architects pair Antigravity with a local Ollama model or Claude Code so they are never locked in.

What is the next step after I install a tool?

Three moves, in order. First, run the verification command from this class so you know the install actually worked. Second, drop the paste-ready CLAUDE.md template into a real project and adapt the seven sections. Third, continue to Foundation 03, where you learn to write prompts as specifications, the skill that turns a tool you can run into software you can ship.