Setup and project context

Installing your tool, the instruction files that tell it how your project works, scoped rules, keeping secrets out of its view, and pointing it at exactly the files that matter.

Installing and starting your tool

Also called install, setup, sign in

What: Getting the tool running inside a real project, signed in with your own account. Start it from the project's root folder so it sees the whole repository and its instruction files.
Why: Most early confusion comes from starting in the wrong folder, an old version or the wrong account. A clean setup saves hours later.

Shell

# macOS, Linux, WSL (native installer)
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
cd my-project
claude            # start a session, log in on first use
claude update     # update a native install

Watch out

Launching the tool from your home folder, so it cannot see the project or, worse, can see everything else.

Project instructions file

Also called CLAUDE.md, copilot-instructions.md, project rules, custom instructions, memory file

What: A Markdown file in the repository that the tool loads into every session: how to build and test, conventions that differ from the defaults, and gotchas. Each tool has its own file name.
Why: Models forget everything between sessions. A short, accurate file stops you repeating the same corrections and keeps the whole team's sessions consistent.

MARKDOWN

# CLAUDE.md (project root, committed)
## Commands
- Test one file: npm test -- path/to/file
- Typecheck: npx tsc --noEmit
## Conventions
- ES modules only; no default exports
- Never edit files in src/generated/

Watch out

Writing a long essay: instructions that do not change behaviour bury the ones that do. Claude Code's docs suggest under 200 lines per file.

AGENTS.md

Also called agents file, cross-tool instructions

What: A plain Markdown instructions file at the repository root that many coding agents read. Cursor and Copilot in VS Code read it directly; Claude Code reads it when there is no CLAUDE.md, or you import it from CLAUDE.md with a line saying @AGENTS.md.
Why: One shared file means the whole team gets the same guidance whichever tool each person uses, instead of three copies drifting apart.

Watch out

Keeping AGENTS.md and a tool-specific file with different, conflicting rules, so each tool follows a different truth.

Generating a starter file

Also called /init, /create-rule, /create-instructions

What: A built-in command that reads your codebase and drafts the instructions file for you, which you then edit down.
Why: It gets the build and test commands right quickly. Your job is to delete the obvious, correct what it guessed and add what it could not see.

Code

/init      # drafts CLAUDE.md, or suggests edits
/memory    # open and edit CLAUDE.md files

Watch out

Committing the generated file unread, including wrong commands it guessed from an old README.

Path-scoped rules

Also called globs, applyTo, paths, file-specific instructions

What: Extra instruction files that load only when the tool works on matching files, such as test files or one folder, so specialised guidance does not fill every session.
Why: They keep the main file short and put rules next to the code they govern, like "API handlers validate input with zod".

MARKDOWN

# .claude/rules/api.md
---
paths:
  - "src/api/**/*.ts"
---
- Validate every request body with zod

Watch out

A glob that matches nothing, so the rule silently never loads. Test it by asking the tool which rules it is following.

Keeping files out of context

Also called .cursorignore, content exclusion, deny rules, ignore file

What: Settings that stop the tool reading certain files, such as .env files, keys and customer data. Each tool does it differently, and none of them is a complete security boundary.
Why: Anything the tool reads may be sent to a model provider. Blocking secrets by default is cheaper than rotating a leaked key.

Code

// .claude/settings.json
{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  }
}

Watch out

Relying on ignore rules alone: terminal commands the agent runs can still read the file. Keep real secrets out of the project folder.

What belongs in instructions

What: Commands the tool cannot guess, conventions that differ from the defaults, architecture decisions, environment quirks and known traps. Leave out what it can read from the code and general advice like "write clean code".
Why: Every line costs context and competes for attention. The test for each line: would removing it cause a mistake?
Example: Useful: "Run pnpm test:unit, not npm test; the e2e suite needs Docker." Useless: "Use meaningful variable names."

Watch out

Never updating the file, so it keeps telling the tool to use a script that was renamed months ago.

Pointing at exact context

Also called @ mention, hash mention, file reference, attach context

What: Naming the specific files, folders, terminal output or diffs the tool should read, instead of describing where code lives and hoping it searches well.
Why: Precise context gives faster, more accurate answers and uses less of the context window than letting the tool explore.

Code

@src/auth/session.ts   # read this file first
!npm test               # run it, output joins the chat
cat error.log | claude -p "explain this error"

Watch out

Attaching the whole repository "to be safe", which drowns the one file that matters.

Go deeper