Claude Code: Getting Started & Core Workflows
A six-chapter, practical Claude / Claude Code learning path covering installation, first projects, repository exploration, edits and debugging.
- Author
- absequ
- Published
- Updated
- Category
- AI Tools
- AI Tools
- Claude / Claude Code
- learning path
- core workflows
Six ordered tutorial chapters. Prerequisites: basic programming and Git; the core path starts from tool installation. The professional path assumes you have finished the core path or can demonstrate the same edit–verify–review loop.
Official tool documentation checked on 2026-11-06. Examples are original teaching exercises for a disposable notes project, not instructions to alter the absequ repository. Platform, account, model, privacy and permission controls can change; follow the cited current documentation for your installation.
- Distinguish Claude chat from Claude Code
- Install Claude Code and verify account access
- Create a tested function through an explicit task contract
- Trace an unfamiliar repository using targeted context
- Plan and implement a small feature with tool approvals
- Reproduce a bug and recover from an incorrect edit
On this page
1. Distinguish Claude chat from Claude Code
Learning objectives: Choose the right Claude interface and prepare a project where agent actions are observable.
Prerequisites: Basic programming and permission to use an AI tool on a disposable project. No prior knowledge of this tool is assumed.
Claude conversational interfaces are useful for discussing a design or explaining supplied code. Claude Code is the coding agent that can inspect a repository, edit files and run tools. Discussing a patch in chat does not put that patch into a checkout or execute its tests. This path uses the terminal CLI so you can inspect each effect directly.
Claude Code also has supported IDE, desktop and browser workflows, with access and provider differences. A Claude account is not proof that every surface or organization feature is enabled. Start on an operating system listed in the current setup guide: macOS, supported Linux/WSL or native Windows. Native Windows and WSL have different shell and sandbox capabilities; choose the environment that owns your project tools.
Practice in order:
- Check Git and Node in your intended terminal. Use a supported Node version with the built-in test runner; Node 24 is suitable for this lab, but it is a project runtime choice, not a requirement of every Claude installation method.
- Create a disposable claude-notes-lab directory and initialize Git. Keep it outside a folder containing production environment files or customer data.
- Write down the distinction between what an answer claims and what a command verifies. You will use a tiny notes function so that every generated line is reviewable.
git --version
node --version
mkdir claude-notes-lab
cd claude-notes-lab
git initExpected outcome: You have a directory with local Git metadata and a working JavaScript runtime. Nothing has been pushed and no service is configured. You can explain why granting a tool file/command access is a separate decision from asking Claude a question.
Common mistakes and troubleshooting: If a coworker uses Claude Code through a managed provider, do not copy their credentials or assume their account configuration applies to you. If you are in WSL, install and run the Linux tooling there rather than mixing paths with a native Windows session.
Summary: Your learning environment is ready. Next install Claude Code and verify its account and permission state.
2. Install Claude Code and verify account access
Learning objectives: Use an official installer, diagnose PATH/authentication separately and inspect permissions before editing.
Prerequisites: Complete chapter 1: Distinguish Claude chat from Claude Code.
The setup guide recommends native installation and documents platform-specific alternatives. The macOS/Linux/WSL installer below downloads and runs a shell script; inspect the source and follow your organization software policy first. PowerShell users must use the documented Windows installer, not paste a Bash pipeline into the wrong shell.
After installation, running claude starts the sign-in flow. Access can come through an eligible Claude subscription, Anthropic Console or a supported managed provider. These are not interchangeable billing arrangements. Follow the supported authentication path for your organization, and do not put an API key in CLAUDE.md, a source file or a chat transcript.
Practice in order:
- Install from the official setup page, reopen the terminal if needed and run claude --version. A missing executable is usually a PATH or installation issue to resolve before investigating project code.
- Run claude in the lab and follow the account prompts. Use claude auth status to inspect authentication without displaying credential files. Avoid sharing raw diagnostic output until it has been reviewed for sensitive data.
- Run claude doctor for installation/settings diagnostics. Inside a session inspect /permissions. Keep the default permission posture for the first exercises instead of enabling blanket bypass.
curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
claude auth status
claude
# In the session, inspect /permissions.Expected outcome: The CLI opens from the intended project and authentication succeeds for the intended account/provider. A diagnostics report is not a test of your application; it establishes that the tool can start and read its configuration.
Common mistakes and troubleshooting: Native installation and package-manager installation have different update behavior. Do not stack two methods without checking which executable PATH resolves. An eligible web-chat account or paid API balance alone may not enable your chosen enterprise provider configuration.
Summary: You can start an authenticated session with known controls. Next give it a tiny implementation task and inspect the actual output.
3. Create a tested function through an explicit task contract
Learning objectives: Ask Claude Code to implement a small immutable function with meaningful tests and no new packages.
Prerequisites: Complete chapter 2: Install Claude Code and verify account access.
The notes lab separates a function contract from implementation choices. You will create addNote(notes, text), returning a new array containing a trimmed nonempty title. The list exists only in memory as a teaching fixture. No database, authentication or framework is needed to learn the edit-and-test loop.
Ask Claude to describe the intended files before editing. After the change, read both implementation and tests. A useful test asserts that the original list remains unchanged; a weak test just checks that the function returned something. Terminal tools can execute code, so review the proposed verification command before approval.
Practice in order:
- Use the supplied prompt in the lab session. Request exactly notes.mjs and notes.test.mjs using node:test and node:assert/strict, with no dependencies or provider calls.
- Inspect git status --short, both new files and any diff. Untracked file contents must be opened explicitly; plain git diff may show nothing for them.
- Approve node --test notes.test.mjs and read the real exit status. Ask Claude to report which assertions passed and any untested assumptions, then keep the next task separate.
Propose and then create two files in this empty lab: notes.mjs and notes.test.mjs.
Export addNote(notes, text). Trim text; reject blank text; return a new array
with a note containing id and title; do not mutate the caller array.
Use node:test and node:assert/strict. Test trimming, blank rejection and
immutability. No dependencies, network access, staging or commits.// notes.mjs — a reference to compare with your agent's result
export function addNote(notes, text) {
const title = text.trim();
if (!title) throw new Error('Title required');
return [...notes, { id: notes.length + 1, title }];
}
// notes.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { addNote } from './notes.mjs';
test('trims the title without changing the input', () => {
const before = [];
assert.deepEqual(addNote(before, ' Learn agents '),
[{ id: 1, title: 'Learn agents' }]);
assert.deepEqual(before, []);
});
test('rejects a blank title', () => {
assert.throws(() => addNote([], ' '), /Title required/);
});Save the two labelled portions as separate files. The reference tests should report two passing tests with node --test notes.test.mjs. The lab uses sequential in-memory IDs only to keep this first exercise small; deletion, concurrent writers and durable identity require a separate data design.
Expected outcome: The resulting files are small enough to understand, and the focused command checks the three requested behaviors. You can reproduce the check without relying on Claude to explain what it would have done.
Common mistakes and troubleshooting: If the agent expands the exercise into an Express app, narrow the request before accepting the files. If it installs a test framework unnecessarily, inspect why instead of approving the command automatically. Never treat a fluent test summary as proof of execution.
Summary: You have completed a controlled implementation cycle. Next learn to inspect a repository whose structure is not known in advance.
4. Trace an unfamiliar repository using targeted context
Learning objectives: Find actual callers, instructions and checks before asking for a patch.
Prerequisites: Complete chapter 3: Create a tested function through an explicit task contract.
Repository exploration should answer a concrete engineering question. Ask how a note is created or where an API response is validated, rather than requesting a summary of every file. Claude Code can inspect files and search symbols, but its overview can still miss a route or mistake an archived example for production code.
Project instructions commonly live in CLAUDE.md. Their purpose is durable context, not a guarantee that the operating system denies forbidden actions. Read the README, active entrypoints and tests alongside instructions. In a Next.js example, follow a page into the interactive component and server action, then confirm which helper actually sends the request. For another framework, trace the equivalent route/controller/service boundary.
Practice in order:
- Record git status --short yourself and tell Claude which existing changes belong to someone else. Ask for no modifications or command execution during initial investigation.
- Request a source map limited to one flow, including instruction files, data types, validation and test locations. Require file/function references and explicit unknowns.
- Open one referenced caller and one test. Ask a follow-up question about an edge case, such as malformed query input, before approving any implementation plan.
Read-only: explain the note-creation flow using actual entrypoints and callers.
Identify loaded project instructions and the existing test runner.
Separate active code from archived examples. Cite files and functions.
Do not open .env files, execute commands, edit files or contact providers.Expected outcome: You can navigate from a user entrypoint to the behavior being changed, and you know which check would exercise it. Any lack of persistence or authorization is reported as a missing design decision, not automatically filled in by the agent.
Common mistakes and troubleshooting: Context grows quickly when every search result is pasted into a conversation. Ask for the few relevant files and a compact evidence summary. If a referenced file does not exist, treat the claim as unverified and request direct inspection.
Summary: You can ground a task in source evidence. Next turn that evidence into a constrained edit with a clear acceptance edge.
5. Plan and implement a small feature with tool approvals
Learning objectives: Separate a proposed change from permission to execute it, then review a measurable result.
Prerequisites: Complete chapter 4: Trace an unfamiliar repository using targeted context.
In the notes lab, the next requirement is to reject trimmed titles longer than 80 JavaScript code units. This intentionally specifies the measurement so the assistant does not invent a Unicode policy. Existing blank-title behavior and immutability must remain unchanged. A good task plan identifies the affected function, test cases and exact command needed to verify them.
Claude Code permission modes and tool rules govern which actions need approval. Read the proposed command and its directory, not only its description. An instruction saying wait for approval is valuable workflow context, while configured permissions are the enforcement layer. Use the permission UI documented for your version and organization instead of copying bypass flags from unrelated examples.
Practice in order:
- Ask Claude to propose a small plan without editing. Include 79/80/81-character boundary cases and require the existing node:test runner.
- Approve the bounded edit after checking the files and acceptance criteria. Keep dependency changes, commits and service calls outside that approval.
- Inspect the diff and authorize the focused test. Ask whether the old blank-title and array-immutability tests still pass, then record what remains outside the exercise.
Plan first: limit trimmed note titles to 80 JavaScript code units.
Preserve blank rejection and immutable arrays. Explain affected files and
79/80/81 boundary tests, then wait for approval before editing.
After approval use the existing runner only. No dependency changes,
network, Git staging, commits or pushes.Expected outcome: A small patch and real boundary tests establish the new contract. A rejected command should produce an explanation of the permission boundary; it should not cause the assistant to silently choose a more powerful execution path.
Common mistakes and troubleshooting: If Claude requests a broad permission for a narrow check, inspect the command composition and ask for a smaller operation. A passing test after removing the rejection assertion is not a successful implementation. Keep behavior changes separate from opportunistic refactors.
Summary: You can approve and review an edit precisely. Next investigate a failure and recover safely when the first attempt is wrong.
6. Reproduce a bug and recover from an incorrect edit
Learning objectives: Use a minimal failing case, preserve user changes and finish with an honest verification report.
Prerequisites: Complete chapter 5: Plan and implement a small feature with tool approvals.
When a generated change fails, start with a reproducible symptom and the exact expected outcome. In the lab, show that a title with 81 code units is accepted even though the contract says it must be rejected. Ask Claude to explain the condition and suggest one discriminating check before changing several files.
A failure can be in code, a test assumption or the execution environment. An unavailable dependency or denied command is different from a failing assertion. Do not solve either by removing tests. Ask for baseline behavior and a minimal correction; broaden verification when changed consumers or a new failure justify it.
Practice in order:
- Provide the sanitized command/output and point to the failing test. Have Claude reproduce it with node --test notes.test.mjs.
- Approve one correction and ask for a review of boundary conditions and the original input-array contract. Compare the diff with the stated plan.
- If the correction is wrong, preserve a diff and undo only the agreed hunks. Inspect any checkpoint/restore action for its scope before using it; Git and manual edits remain the source of truth.
Bug report: the 81-code-unit title is accepted. Expected: rejection.
Reproduce with node --test notes.test.mjs and explain why the existing guard
is insufficient. Make a minimal patch, rerun the relevant tests and report
commands/results separately from unverified behavior. Do not reset the checkout.Expected outcome: The failure is reproduced and corrected, or an environment blocker is identified with evidence. The handoff names changed files and checks, without claiming UI or service correctness from a pure-function test.
Common mistakes and troubleshooting: If an unrelated user edit disappears, stop and compare against the recorded baseline rather than asking for another broad regeneration. Never paste real token-bearing logs into a debugging prompt; replace sensitive values with structural examples.
Summary: You have finished the Claude Code core loop. Continue to the professional path for instructions, team workflows and controlled extensions.
References
Claude Code overview — Anthropic
Claude Code setup — Anthropic
Claude Code CLI reference — Anthropic
Claude Code permissions — Anthropic
Claude Code best practices — Anthropic
Project instructions and memory — Anthropic