Claude Code Tutorial for Beginners: Setup, Commands, and Real Workflows

Claude Code Tutorial for Beginners

Claude Code is an AI coding tool that works from your terminal and can interact with the project stored on your computer. Instead of manually pasting every file into a chat, you can open the project directory, start a session, and ask questions about the codebase.

It can help explain unfamiliar code, find relevant files, plan a feature, edit code, run tests, investigate errors, review changes, and support Git tasks. It should still be treated as an assistant rather than an automatic replacement for developer judgement.

This Claude Code tutorial explains how to install the tool, start a project safely, use essential commands, write better prompts, review changes, and build practical workflows. Developers who need professional implementation support can also browse Web Development services or post a coding project on UstadWork.

What Is Claude Code?

Claude Code is designed to work inside a development environment rather than only through a browser chat window. You launch it from a terminal inside a project directory and communicate with it using natural-language instructions.

Depending on the task and the permissions you approve, it can:

Explore folders and files.
Explain project structure and application logic.
Search for functions, routes, components, and configuration.
Propose or make file changes.
Run development commands and tests.
Investigate error messages and failing builds.
Review Git changes and commit history.
Help prepare commits and pull requests.
Create or update project documentation.

The main advantage is project context. It can examine several relevant files instead of responding only to one isolated code snippet.

What Claude Code Cannot Safely Decide for You

Claude Code can make development faster, but it does not remove the need for human review. It may misunderstand requirements, select an unsuitable library, introduce a security problem, change unrelated code, or produce an implementation that passes a simple test but fails in production.

You should remain responsible for:

Confirming the business requirement.
Reviewing proposed commands.
Checking edited files.
Protecting secrets and customer data.
Approving dependencies.
Running relevant tests.
Reviewing security-sensitive code.
Deciding whether a change is ready for deployment.

Use it like a capable pair programmer: provide context, ask for a plan, review the work, test the result, and keep important decisions under human control.

What You Need Before Installation

Before installing Claude Code, prepare:

A terminal: Terminal on macOS or Linux, PowerShell, Windows Terminal, Git Bash, or WSL depending on your setup.
A code project: An existing repository is useful for practice, although you can also start inside a new folder.
Git: Recommended when you want to review, restore, branch, or commit changes safely.
A supported Claude account: Available login and billing options can depend on your account or organisation.
A clean working tree: Commit or safely store existing work before allowing an AI tool to edit the project.

Always review Anthropic's current system requirements before installing because supported operating systems and installation methods can change.

Install Claude Code With npm

One documented installation method uses npm. First confirm that Node.js and npm are available:

node --version
npm --version

Install Claude Code globally:

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

Do not add sudo to the global npm installation. Using sudo can create permission and security problems. Fix the Node or npm permission setup instead.

After installation, check that the command is available:

claude --version

You can also use:

claude doctor

This helps inspect the installation when something is not working as expected.

Native Installation Options

Anthropic also documents native installation methods for supported systems. These methods may change more frequently than the basic workflow, so copy the current command from the official Claude Code quickstart rather than relying permanently on an old article or screenshot.

After native installation, the normal workflow remains similar:

cd /path/to/your/project
claude

To update an existing installation, the CLI may support:

claude update

Keep the tool updated so you receive current features and security fixes.

Claude Code Setup on Windows

Windows users may work through WSL or a supported native terminal setup. The best option depends on the project tools already being used.

WSL: Useful when the development project expects a Linux-style environment, shell commands, permissions, package tools, or deployment workflow.
Git Bash or supported native setup: Can be suitable for projects already working correctly in a Windows environment.

Avoid mixing Windows and Linux installations of Node, npm, Git, and project dependencies inside the same workflow. For example, a WSL project should normally use the Node installation inside WSL rather than accidentally calling a Windows Node executable.

Confirm the active paths with commands such as:

which node
which npm
which git

Sign In and Start Your First Session

Open the terminal and move into the project directory:

cd /path/to/your/project

Start Claude Code:

claude

The first launch may ask you to authenticate. Follow the account instructions shown in the terminal. Available authentication choices can depend on your subscription, API access, organisation, or cloud environment.

Always launch Claude Code from the correct project folder. The working directory helps determine which files and subdirectories belong to the current task.

Begin by Asking Claude to Understand the Project

Do not begin an unfamiliar codebase by immediately asking for a large rewrite. First ask Claude Code to inspect and explain the project.

Useful beginner prompts include:

What does this project do?
Explain the folder structure.
Which file starts the application?
What frontend and backend technologies are used?
Where is authentication handled?
How does data move from the form to the database?
Which commands run the application and tests?

Compare the explanation with the README, package files, configuration, and your own understanding. This exploration stage reduces the risk of editing the wrong layer.

Essential Claude Code Commands

These commands cover many beginner workflows:

Start an interactive session:
claude

Start with an initial request:
claude 'explain this project'

Run one request and exit:
claude -p 'explain the authentication middleware'

Continue the most recent conversation:
claude -c

Resume a previous session:
claude --resume

Update Claude Code:
claude update

Check help:
claude --help

Some commands and flags evolve over time. Confirm advanced automation flags from the current CLI reference before using them in scripts.

Use Plan Mode Before Important Changes

A safer workflow is to separate planning from editing. Ask Claude to inspect the code and explain the proposed approach before changing files.

You can request this conversationally:

Analyse this requirement. Do not edit files yet. Show the relevant files, risks, and implementation plan.

The CLI also supports permission modes, including a planning-oriented mode in current documentation:

claude --permission-mode plan

Review the proposed plan for:

Correct understanding of the requirement.
Files that will be changed.
Database or API impact.
Security concerns.
Backward compatibility.
Tests that should be added.
Potential edge cases.

Only move to implementation after the plan matches your actual goal.

How to Ask Claude Code to Build a Feature

A weak prompt such as build a dashboard leaves too many decisions undefined. A stronger prompt gives the current context, required behaviour, constraints, and completion criteria.

Example:

Inspect the existing admin area. Add a customer dashboard that lists open orders. Reuse the current authentication and design components. Do not add a new UI library. Include loading, empty, and error states. Write tests for the data-mapping function. Show me the plan before editing.

This prompt explains:

Where the feature belongs.
What the user should see.
Which existing systems to reuse.
Which dependency should not be added.
Which interface states are required.
Which test should be created.
That approval is required before editing.

Specific constraints generally produce more reviewable results.

Use Small Implementation Steps

Large one-shot requests make review difficult. Break a complex feature into milestones:

Step 1: Inspect the current architecture.
Step 2: Propose the data model or API contract.
Step 3: Implement the smallest backend change.
Step 4: Add the interface.
Step 5: Add validation and error states.
Step 6: Write or update tests.
Step 7: Review the complete diff.

After each stage, ask Claude Code to summarise what changed and what remains. This makes incorrect assumptions easier to catch before they spread across the codebase.

Debug an Error With Claude Code

Claude Code can investigate an error more effectively when you provide the full symptom and reproduction details.

Include:

The complete error message.
The command that produced it.
Expected behaviour.
Actual behaviour.
Steps required to reproduce the issue.
Relevant environment details.
Recent changes that may have caused it.

Example prompt:

Running npm test causes this error: [paste error]. It started after the authentication middleware change. Reproduce the issue, identify the root cause, and explain it before making a fix. Keep the patch limited to the failing behaviour and add a regression test.

Ask for the root cause rather than accepting the first patch that hides the error.

Ask Claude Code to Run and Interpret Tests

A useful workflow is to let Claude identify the correct project commands, run the relevant test scope, and explain failures.

Prompts may include:

Find the test commands used by this repository.
Run only the tests related to user registration.
Explain why this test fails without changing the code.
Update the implementation and add a regression test.
Run the linter, type checker, and relevant unit tests.

Do not treat one successful test as proof that the complete application is correct. Review which tests ran, which important paths remain uncovered, and whether integration or manual testing is still required.

Review and Refactor Existing Code

Claude Code can help identify duplication, complex functions, unclear naming, missing tests, and inconsistent patterns. The refactor request should preserve behaviour unless a change is explicitly required.

Example:

Review the order-calculation module. Identify duplication and hard-to-test logic. Propose a refactor that preserves public behaviour. Do not add dependencies. Show the plan and required tests before editing.

After implementation, ask:

Show the files changed and explain why each change was necessary.
What behaviour could accidentally have changed?
Which tests verify that existing behaviour remains intact?

A refactor should improve maintainability without silently changing product rules.

Use Claude Code With Git

Git gives you a safety layer when experimenting with AI-assisted changes. Begin from a clean branch and review the working tree regularly.

Useful prompts include:

Show me which files have changed.
Summarise this diff by feature and risk.
Review the current changes for bugs and missing tests.
Suggest a clear commit message.
Find the commit that introduced this behaviour.
Help me understand this merge conflict before resolving it.

Do not automatically commit or push changes you have not reviewed. Check the diff yourself and confirm that secrets, generated files, unrelated formatting, and temporary debug code are not included.

Create a CLAUDE.md Project Guide

A CLAUDE.md file can store project instructions that Claude Code should understand across sessions. This reduces repeated explanations and helps team members use more consistent workflows.

A project guide may contain:

Application architecture.
Important directories.
Build, test, lint, and development commands.
Code style and naming conventions.
Database migration rules.
Approved dependencies.
Security-sensitive areas.
Files that should not be edited automatically.
Definition of done.
Deployment or handoff notes.

You can initialise project guidance through the available session commands, including /init where supported, or create the file manually.

Example CLAUDE.md Structure

# Project Overview
This is a Django marketplace with Bootstrap templates and PostgreSQL.

# Important Commands
- Run tests: python manage.py test
- Run server: python manage.py runserver
- Format Python: ruff format .

# Development Rules
- Reuse existing models and template components.
- Do not change database fields without explaining the migration.
- Do not add dependencies without approval.
- Preserve existing URL names.
- Add tests for business-rule changes.

# Security
- Never print environment variables or secrets.
- Do not modify production credentials.
- Ask before changing authentication or payment code.

# Definition of Done
- Relevant tests pass.
- Mobile layout is reviewed.
- No unrelated files are changed.
- Implementation and risks are summarised.

Keep instructions specific and current. Remove outdated commands and rules when the project changes.

Write Better Claude Code Prompts

A strong coding prompt usually contains six parts:

Context: Which application, feature, or user flow is involved?
Goal: What result should the user receive?
Scope: Which work is included and excluded?
Constraints: Which tools, patterns, or dependencies must be reused or avoided?
Validation: How should the result be tested?
Process: Should Claude plan first, ask questions, or edit immediately?

Template:

Inspect [area]. We need [result] for [user]. Reuse [existing system]. Do not change [protected area]. Include [edge cases]. Add or update [tests]. First explain the relevant files and proposed plan. Ask before making destructive or security-sensitive changes.

Give Claude Acceptance Criteria

Acceptance criteria make completion measurable.

Example for a registration form:

Email must be required.
Invalid email must show an inline error.
Password must meet the existing policy.
Duplicate email must not create another account.
Server errors must show a safe message.
Existing users must remain unaffected.
Relevant automated tests must pass.

Ask Claude Code to repeat the acceptance criteria before implementation and confirm each one after testing. This reduces the chance that the tool solves only the most obvious part of the request.

Review Permissions Before Approving Actions

Claude Code uses a permission system for actions such as editing files or running commands. Review each proposed action according to its impact.

Before approving a command, ask:

What files can it change?
Can it delete data?
Can it install or update dependencies?
Can it contact an external service?
Can it access credentials?
Can it modify the database?
Can it push code or change deployment infrastructure?

Avoid permission-bypass options during normal development, particularly on production systems, repositories containing sensitive code, or machines with broad credentials.

Protect Secrets and Sensitive Data

Do not place private API keys, passwords, production database values, customer information, confidential documents, or unrestricted cloud credentials inside prompts.

Use safer practices:

Store secrets in environment variables or an approved secrets manager.
Use development or test accounts.
Remove personal data from error examples.
Limit access to required directories.
Review configuration before sharing project context.
Use individual permissions rather than shared administrator accounts.
Rotate any credential that may have been exposed.

Security-sensitive authentication, payment, permissions, encryption, and infrastructure changes should receive experienced human review.

Use Development Containers for Risky Work

A development container or isolated environment can reduce risk when Claude Code needs to run unfamiliar commands, install packages, execute migrations, or work with an untrusted repository.

An isolated environment can help limit access to:

Personal files.
Host credentials.
Production accounts.
Unrelated repositories.
Local databases.
System-wide tools.

Isolation does not remove the need to review commands. It creates an additional boundary when experimenting or evaluating third-party projects.

Connect External Tools Through MCP Carefully

The Model Context Protocol can connect AI applications to external tools and data sources. In a development workflow, MCP may provide controlled access to systems such as documentation, design files, issue tracking, repositories, or internal services.

Before adding an MCP server:

Confirm who created and maintains it.
Review the permissions it requests.
Understand which data it can read or change.
Use the minimum required credentials.
Test it in a non-production environment.
Remove servers that are no longer needed.

Do not install an unknown MCP server only because it appears in a public list. External integrations can introduce privacy, prompt-injection, supply-chain, and account-access risks.

Practical Workflow: Fix a Form Validation Bug

Here is a complete beginner workflow:

1. Start a clean branch.
git checkout -b fix/registration-validation

2. Start Claude Code.
claude

3. Explain the issue.
Users can submit the registration form with an empty phone field. Inspect the form, server validation, and tests. Do not edit yet.

4. Review the proposed root cause and plan.
Confirm that the correct model, form, request handler, and template are identified.

5. Approve a limited implementation.
Implement the smallest safe fix. Reuse the existing validation pattern and add a regression test.

6. Run relevant checks.
Run the registration tests and the project linter. Explain any failure.

7. Review the diff.
Summarise every changed file and identify possible side effects.

8. Test manually.
Verify empty, invalid, and valid phone values through the interface.

9. Commit only after human review.

Practical Workflow: Build a Small Feature

Suppose you need a saved-jobs feature:

Discovery:
Find the current job model, authenticated-user pattern, and similar bookmark functionality. Explain the architecture without editing.

Planning:
Propose the smallest saved-jobs design. Include database impact, URL flow, permissions, UI states, and tests.

Implementation:
Implement the approved backend model and save/remove endpoints. Do not change unrelated job logic.

Interface:
Add save and remove actions using existing button styles. Include saved, loading, and error states.

Validation:
Run relevant tests, check authentication boundaries, and review the final diff for duplicate queries and permission problems.

This staged process is easier to review than asking Claude to build the complete feature in one uncontrolled request.

Common Claude Code Mistakes

Avoid these beginner mistakes:

Starting in the wrong folder: Claude receives the wrong project context.
Requesting a large rewrite immediately: Important architecture and constraints are missed.
Using vague prompts: Claude must invent too many requirements.
Approving every command automatically: Risky or destructive operations may run unnoticed.
Not using Git: Restoring unwanted changes becomes harder.
Skipping tests: A visually correct feature may break existing behaviour.
Sharing secrets: Sensitive credentials or data may be exposed.
Accepting new dependencies without review: Maintenance and security risk increases.
Ignoring the diff: Unrelated changes may enter the commit.
Deploying directly from an AI session: Production changes bypass normal review and release controls.

Claude Code Beginner Checklist

Before using Claude Code on a real project, confirm that:

The correct repository is open.
Existing work is committed or backed up.
The application runs before changes begin.
The relevant test command is known.
A clear task and acceptance criteria are written.
Claude is asked to inspect and plan first.
Permissions are reviewed before approval.
No sensitive secrets are placed in prompts.
Changes remain inside the intended scope.
The final diff is reviewed manually.
Tests, linting, and type checks are run where relevant.
The feature is tested through the real user flow.
Documentation and project memory are updated.

Developers needing implementation support can browse development services, post a custom coding project, or review the UstadWork FAQ.

A Seven-Day Claude Code Learning Plan

Day 1: Install Claude Code and explore a small practice repository.
Day 2: Ask architecture, file-structure, and data-flow questions.
Day 3: Fix one small bug using plan, edit, test, and review stages.
Day 4: Add tests and practise explaining failures.
Day 5: Create a useful CLAUDE.md for the project.
Day 6: Review Git history, summarise a diff, and prepare a clean commit.
Day 7: Build one small feature with written acceptance criteria.

Use a practice repository or development environment rather than experimenting first on production code.

When to Hire a Developer Instead of Relying on AI

Claude Code can accelerate development, but professional support is valuable when the project includes:

Payment processing.
Authentication or permissions.
Customer or regulated data.
Production database migrations.
Infrastructure and deployment changes.
Complex security requirements.
Large legacy systems.
Performance-critical architecture.
Unclear product requirements.
A deadline requiring reliable ownership and support.

A developer can validate the architecture, review AI-generated changes, test edge cases, manage deployment, and remain accountable for the complete result.

Use our startup developer hiring guide when that page is live, or read React vs Vue for a startup MVP when planning a new frontend.

Use Claude Code as a Reviewed Development Partner

Claude Code is most useful when it supports a disciplined development process. Begin with project understanding, provide clear requirements, request a plan, approve limited actions, run tests, and review every important change.

Do not measure success only by how quickly code appears. Measure whether the implementation matches the requirement, follows the existing architecture, handles important edge cases, remains secure, and can be maintained by another developer.

A strong Claude Code workflow combines AI speed with human judgement, Git history, automated testing, written project instructions, and controlled permissions.

Ready to work on a real project? explore Web Development services, post your development requirements, or browse experienced developers on UstadWork.