Claude Code Tutorial: Install, CLAUDE.md and Permissions

Claude Code is a coding agent that runs in the terminal. It is not a chat window: you open it in a project directory, and it reads the project structure on its own, edits multiple files, runs tests, and opens PRs. The barrier to using it well is not how good your English is. It is whether you are willing to spend twenty minutes setting up CLAUDE.md and permissions first, so that you stop repeating yourself every day afterward.

This is the complete tutorial for first-time users: installation, the right way to use it on day one, the four commands you must learn, how to write CLAUDE.md, how to choose a permission mode, and how to switch the model endpoint to your own provider. The commands in this article were run for real on claude 2.1; check your version with claude --version before you start.

Installation and First Launch

You need Node.js 22 or later (the official requirement at the time of writing; it may rise over time, so if the install fails, check node -v first):

npm install -g @anthropic-ai/claude-code
claude --version

cd into your project, then:

claude

The first launch asks you to complete login (a subscription plan or an API key, choose one). After logging in, the first thing to do is not to ask it to write features. First, have it read and understand the project:

Take a look at this repo's structure first. Tell me how the main modules are divided and where the data flow comes in.

The reason is practical: how accurate its answer is tells you whether it can grasp this project's context. If it can't, you need to add to CLAUDE.md. If it can, you know how large a task you can safely hand off.

The Four Commands to Learn on Day One

/clear is the one newcomers most often overlook and veterans use most aggressively. If the context still holds an approach you abandoned thirty minutes ago, it will keep looping back to it. One task = one clean context.

Two more worth learning early:

• Plan mode: have it present a plan without touching anything. Before a large change, enter plan mode; once you confirm the direction is right, approve it. That is less work than reviewing the diff afterward.
• claude -p "<task>": non-interactive mode. The output goes straight to stdout, so it can be piped into scripts or CI.

claude -p "Condense the unreleased section of CHANGELOG.md into a release notes paragraph" > release-notes.txt

CLAUDE.md: The Twenty Minutes with the Highest Return

CLAUDE.md sits in the project root and is loaded automatically every time you start work. It is not documentation; it is instructions. Whatever you write in it is treated as rules to follow.

Run /init first to generate a draft, then manually add the things that really matter. A good CLAUDE.md looks like this:

# Project Rules

## Commands
- Dev: `pnpm dev` (do not use npm)
- Test: `pnpm test -- --run`
- Type check: `pnpm typecheck`

## Conventions
- All API response types are centralized in `src/types/api.ts`
- Do not add third-party packages; ask first
- Use CSS Modules for styling; the project does not use Tailwind
- Write commit messages in Traditional Chinese

## Pitfalls
- Do not refactor anything under `src/legacy/`; external systems depend on it
- Local tests require running `docker compose up -d db` first

Three practical principles:

1. Telling it "what not to do" is more effective than telling it "what to do". It has many default behaviors; what you really need is a fence.
2. Whenever you repeat yourself in a conversation for the second time, write it into CLAUDE.md. This is the best criterion.
3. You can layer them. Put personal preferences (for example, "answer in Traditional Chinese") in the home-directory ~/.claude/CLAUDE.md, team conventions in the project root, and module-specific rules in subdirectories.

Permissions: Let It Run Smoothly Without Running Wild

By default, it asks you about every action that modifies files or runs commands. Approving everything is tedious, and allowing everything is dangerous. The right approach is to add repeated safe actions to an allow list: choose "don't ask again" in the approval prompt, or edit the project's .claude/settings.json directly:

{
  "permissions": {
    "allow": [
      "Bash(pnpm test:*)",
      "Bash(pnpm typecheck)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ]
  }
}

The principle is simple: allow read-only and reversible actions, and do not allow actions that affect the outside world (pushing, deploying, deleting, sending messages, payments). Once that line is clearly drawn, you can safely let it keep working for ten-plus minutes without watching it.

There is one habit more important than any setting: commit before you start making changes. With a clean git state, you can always run git checkout . at any moment to throw away everything it did in one go.

Practical Example: A Workflow You Will Actually Use

Suppose you need to fix a bug. An effective process is:

1. Give it a reproduction path first, not a guess.

   Run pnpm test -- --run src/cart/total.test.ts; the 3rd case is failing. Reproduce it for me first.
   

2. Have it explain the cause before changing anything. If you tell it to fix directly, you get a patch that turns the tests green but that you cannot understand.
3. After the change, have it run the tests to verify. Once the test command is written into CLAUDE.md, it will do this step on its own.
4. Read the diff yourself. There is no shortcut for this step.

When writing a new feature, reverse the order: first use plan mode to have it propose a plan, revise the plan yourself, then approve the implementation. Changing direction at the planning stage costs one-tenth of what it costs at the code stage.

Switching the Model Endpoint

Claude Code's model endpoint can point to other compatible services. It takes three environment variables, with no need to change any project settings. The usual reasons for doing this: you want to try different models within the same toolset, you want the team to share one billing channel, or you need Taiwan-friendly payment methods and invoices.

BazaarLink provides a compatible endpoint, configured like this:

# macOS / Linux
export ANTHROPIC_BASE_URL=https://api.bazaarlink.ai
export ANTHROPIC_AUTH_TOKEN=sk-bl-your-key
export ANTHROPIC_MODEL=anthropic/claude-opus-4.6

claude

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://api.bazaarlink.ai"
$env:ANTHROPIC_AUTH_TOKEN = "sk-bl-your-key"
$env:ANTHROPIC_MODEL = "anthropic/claude-opus-4.6"

claude

Four details you only learn from testing:

1. Fill ANTHROPIC_BASE_URL only up to the domain; do not include /v1. The tool appends /v1/messages on its own. If you include it, the path becomes /v1/v1/messages and returns 404.
2. ANTHROPIC_MODEL must be the full model id, for example anthropic/claude-opus-4.6, anthropic/claude-sonnet-4.6, or anthropic/claude-opus-5. For the list of available models, see the model list.
3. You may see a notice that some model has been retired. That comes from the tool's local string matching on the model name, not from a server response, and it does not affect execution.
4. To revert to your original settings, remove these three environment variables. No project file is changed, so switching is zero-cost.

Get a key at bazaarlink.ai/free. The free tier is enough to run through the whole workflow before you decide whether to top up. The actual rate limits are as stated on that page. For enterprise use and invoicing terms, see enterprise plans.

Common Pitfalls

It keeps asking whether to run commands: add the repeatedly used safe commands to the allow list in .claude/settings.json.

It changed files it should not have: two steps. Restore with git checkout, then write "do not touch X" into CLAUDE.md. If the same mistake happens a second time, the rule was not written down.

Answers start drifting and keep circling back to an old approach: the context is polluted. Restart with /clear; use /compact midway through long tasks.

It says it cannot find a certain command: your project commands are not written into CLAUDE.md, so it can only guess.

Chinese replies mix Traditional and Simplified characters: add one line to ~/.claude/CLAUDE.md: "Always reply in Traditional Chinese (Taiwanese usage)."

Summary

Claude Code's efficiency gap does not come from who writes better prompts. It comes from three fundamentals: whether CLAUDE.md is specific enough, whether you clear context often enough, and whether the permission list is tuned so that safe actions no longer need to be approved. Get these three right, and it goes from a tool you have to watch constantly to a colleague you can hand an entire task.

The model endpoint is swappable, and the tool itself is not locked to a single provider. Switch with three environment variables, and switch back at any time.

TWD billing · Taiwan invoices · leading AI models · OpenAI-compatible API