Claude Code Tutorial: Setup, CLAUDE.md, Skills and a Spec-First Workflow

Claude Code is Anthropic's AI coding tool: it runs in your terminal, reads your project, edits files and runs commands. To get going, install it and log in, put your project rules in CLAUDE.md, turn repeated procedures into skills, and write a spec and then a plan before building a feature. Subagents, hooks and MCP handle side work, rules that must always hold, and connections to outside tools. Feature details follow Anthropic's official documentation.

I pay for both a Claude plan and a GPT plan, and Claude Code is one of the tools I work in. Late last year I started wiring AI into my development process: it helps review pull requests and sometimes handles the merge.

Install and first run

The recommended route is the native installer. On macOS, Linux or WSL:

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

On Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Homebrew (brew install --cask claude-code) and WinGet (winget install Anthropic.ClaudeCode) also work. The native install updates itself in the background; with Homebrew or WinGet you upgrade by hand. When it finishes, open a new terminal window and run claude --version. If it prints a version number, you're set.

Then start it inside a project:

cd /path/to/your/project
claude

The first run asks you to log in. You can use a Claude subscription (Pro, Max, Ultra, Team or Enterprise), a Claude Console account, or a cloud provider such as Amazon Bedrock.

A few commands worth knowing from day one:

• /init reads the project and writes a first CLAUDE.md. If one already exists, it suggests changes instead of overwriting it.
• Shift+Tab switches the permission mode, which decides what Claude may do without asking you.
• /clear wipes the current conversation. Use it before you switch to an unrelated task.
• claude -c continues the most recent conversation in this folder; claude -r lets you pick an older one.

Keep the first task small. The official quickstart suggests letting Claude read the project, asking it what the project does, and then trying one small change.

CLAUDE.md: write down what the code can't tell it

Every new session starts with an empty context. CLAUDE.md is the file Claude Code reads at the start of every session. The three locations you'll use most:

Location	Purpose
~/.claude/CLAUDE.md	Personal preferences, loaded in every project
./CLAUDE.md or ./.claude/CLAUDE.md	Project rules, committed and shared with the team
./CLAUDE.local.md	Your own project-specific notes; add it to .gitignore

What the official docs recommend:

• Keep each file under 200 lines. Longer files take more context and get followed less reliably.
• Make instructions specific enough to check. "Run npm test before committing" beats "test your changes".
• Write only what Claude can't learn from the code: how to run the tests, places where the code is misleading, decisions the team has made, anything you've already corrected twice. Skip the architecture and file layout; Claude reads the repo itself.
• Import other files with @path/to/file, up to four levels deep. Imports help you organize, but the imported text still costs context.

Here is an excerpt of the CLAUDE.md in my website repo (trimmed):

# personal-website — agent notes

- Design spec: read `DESIGN.md` before changing anything visible.
- Work directly on `main` unless Kelvin asks for a branch.
  Pushing to `main` deploys (Cloudflare Workers Builds).
- Tests: `npx vitest run`. Mobile checks per `DESIGN.md` §0.5 and §7.
- SEO Monitor: Loaded with: @seo/CLAUDE-SEO.md

The design rules live in DESIGN.md, and CLAUDE.md has one line telling Claude to read it before touching the UI. The SEO guide is maintained by a separate system, so it comes in through an @ import instead of a copy. I wrote about this in Day 5: with the rules in files, the AI has something to go on when it changes a feature, I don't have to repeat myself, and I can edit the file to record decisions it should follow from then on.

At the global level, my ~/.claude/CLAUDE.md is a single line: an @ import of one AGENTS.md file. All the rules live in that file, and Codex reads the same one, so both tools follow one set of rules and I edit it in one place. The docs also say Claude Code reads a repo's AGENTS.md directly when there is no CLAUDE.md. When both exist, it reads only CLAUDE.md by default, so to share one file you import it with @AGENTS.md from CLAUDE.md.

Skills: turn a repeated procedure into a skill

A skill is a folder with a SKILL.md file in it. The YAML frontmatter tells Claude when to use it, and the body holds the steps to follow:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks.

Claude Code runs the !`git diff HEAD` line first and swaps in its output, so Claude reads the skill with the current diff already in place.

Put it in ~/.claude/skills/<name>/SKILL.md and it's a personal skill, available in every project. Put it in a project's .claude/skills/<name>/SKILL.md, commit it, and your team gets it too. Claude normally sees only each skill's description and loads the full text when it decides the skill is relevant. You can also call one directly with /skill-name. Custom commands in .claude/commands/ have been merged into skills, and existing command files keep working.

Skills other people build are usually shipped as plugins. Anthropic's official marketplace is added for you the first time you open an interactive session; for any other source, add the marketplace first:

/plugin marketplace add owner/repo
/plugin install name@marketplace

A plugin can bring hooks and MCP servers with it, so read what it installs before you install it.

Where I find skills is the subject of my Day 6 post. I start with open-source projects, from China and the US alike, and I look for versions in other languages. Chinese open-source communities often build on an overseas project and add more Chinese documentation and detail, and following the original and its forks often turns up something different. I also keep an eye on skills people share on X. In my workflow I use Superpowers' brainstorming and writing-plans, and humanizer-zh-tw to edit Chinese drafts.

As for sharing: I use both Claude Code and Codex, and they read skills from different folders (~/.claude/skills for Claude Code; on the Codex side I use ~/.agents/skills). I keep a git repo just for AI configuration:

• skills/: skills I maintain myself
• vendor/: snapshots of third-party skills, never edited in place; to update one I replace the whole folder with the new version
• skills.manifest: skills whose source lives in other project repos, one per line

A setup.sh script symlinks all of them into both folders. Both sides point at the same files, nothing is copied, and a skill installed on only one side gets mirrored to the other. setup.sh --check changes nothing; it lists skills that aren't linked yet, exist on only one side, or have two copies whose contents differ. Third-party skills are snapshots so that a colleague who follows the same steps gets exactly the versions I have.

Write the spec, then the plan, then review before anything runs

When I build a feature with AI, the order is: spec first, then the plan, and a review before anything runs. Day 9 walks through a full example.

AI tends to open with three options, and it's natural to compare them and pick one. But its list may not include the approach that fits you best, because you may not have told it your habits or what actually bothers you. So this is what I do:

1. Brainstorm. Superpowers' brainstorming skill first learns the project and my goal, then asks questions until the requirements are clear.
2. Write the spec: the goal, the user flow, the scope and the definition of done. The implementation has to stay within it. If the plan turns out wrong halfway through, I go back, change the spec, and write down what changed and why.
3. Write the plan. Superpowers' writing-plans breaks the spec into steps that can be executed one by one: what each step delivers, what has to be in place first, how to check it, and where I need to grant permissions or supply settings.
4. Review the plan against the spec. Will these steps, once done, actually solve the problem I started with?
5. Run it. The agent executes, and I check the real result at the end.

Two built-in Claude Code features fit this flow:

• Plan mode. Press Shift+Tab until the status bar shows ⏸ plan mode on, or start with claude --permission-mode plan. Claude reads files and proposes a plan, and edits nothing until you approve.
• /goal. You set a completion condition, and after each turn a separate model checks whether it holds; if not, Claude keeps going. Write the condition as something the conversation can prove, such as "npm test exits 0", and state what must not change along the way.

In Day 5 I gave an example completion condition for an article draft:

Turn the approved outline into a Traditional Chinese article, save it to the specified Studio draft, read it back and confirm the body matches. Keep it pending review and do not publish. If it can't be saved, explain what blocked it and keep the draft.

Where the result goes, how to confirm it was saved correctly, and which actions are out of scope all have to be written down. Only then does the AI have a basis for judging whether it's done.

Subagents: move side work out of the main conversation

A subagent has its own context window, system prompt and tool permissions. Use one when a side task would flood your conversation with search results, logs or file contents you won't look at again: the subagent does the work in its own context and sends back only a summary.

Claude Code ships with a few: Explore (read-only, for searching and analyzing code), Plan (gathers context during plan mode) and general-purpose (multi-step tasks that need both exploration and action). Custom ones go in a project's .claude/agents/ or your personal ~/.claude/agents/, as Markdown with frontmatter:

---
name: reviewer
description: Reviews changed files against the spec they were built from.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec,
and report only the gaps that affect correctness. Skip style.

Give it only read tools and it can look but not edit. Claude Code enforces that limit itself, and no prompt can lift it. The docs also point out that subagents mostly cost tokens, and handing the same task to one won't make the answer better. They help with parallel work, keeping noisy output out of your way, and getting a reviewer who hasn't seen the reasoning behind the code.

One of the skills in my list is subagent-driven-development: when executing a plan, it hands each independent task to a fresh subagent and runs a code review between tasks.

Hooks and MCP

CLAUDE.md and skills are context for the model. It usually follows them, but nothing guarantees it. For things that must always happen, or must never happen, use hooks: shell commands that Claude Code runs at set points in its lifecycle. The harness runs them, so they don't depend on the model deciding to.

The official example runs Prettier after every file edit, configured in the project's .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

PreToolUse fires before a tool runs, and a script that exits with code 2 blocks the action. After setting one up, run /hooks to confirm it loaded.

In my global settings I have a PreToolUse hook that checks SQL before the AI runs it through the Supabase MCP server. Destructive statements, such as dropping a table or wiping its data, bring up a confirmation prompt, so I see the full SQL before I decide.

MCP (Model Context Protocol) is an open standard for connecting Claude Code to external tools and data sources. To add a remote server:

claude mcp add --transport http <name> <url>

The default scope is local: only you, only in this project. Add --scope project and the server goes into .mcp.json at the project root, shared with the team through the repo. My website repo registers an MCP tool for reading SEO data this way. The file holds no keys; the credentials sit in a private config file on the local machine. Keep the official warning in mind as well: verify that you trust a server before connecting it, because servers that fetch external content can expose you to prompt injection.

Common pitfalls

• Treating CLAUDE.md as a manual. Claude reads the architecture and file layout itself, and the longer the file, the less reliably it gets followed. Keep the test commands, the misleading spots and the decisions already made.
• Expecting CLAUDE.md to enforce anything. It's context the model reads, and the model may not follow it. Rules without exceptions belong in a hook or a permission rule.
• Taking "done" as proof. After a tool reports completion, run the relevant tests for code, look at the real screen for UI changes, and for an article confirm it was saved in the right place. You can also ask for evidence directly: which command ran and what it printed.
• Accepting a bare conclusion. I ask: "What data or experimental results is this conclusion based on? Which parts are still assumptions? Walk me through the key steps of the reasoning and give me a way to check it myself." An extra paragraph of explanation from the AI doesn't mean that explanation has been verified.
• Correcting the same thing a third time. The official advice: if two corrections haven't fixed it, run /clear and write one new prompt that includes what you learned, instead of leaving failed attempts in the conversation.
• Picking straight from the AI's options. First ask whether you've fully described the problem you're solving and told it your habits and constraints. Then judge whether its suggestions fit.
• Installing separate copies of the same skill in two tools. Edit one, forget the other, and they drift apart. Symlink both to one source and run the check after you install or remove a skill.
• Installing unfamiliar plugins or MCP servers on a whim. They can run hooks and read external content, so look before you install.

In Day 8 I wrote that the more AI can help with, the more I need to keep my own judgement about what makes a piece of work fit to use. These settings write down the basis for that judgement: rules in CLAUDE.md, procedures in skills, goals and definitions of done in the spec. When I go back to check, there's something to check against.