Claude Code tutorial

This Claude Code tutorial is a process walkthrough—not a substitute for Anthropic’s Claude Code documentation. Claude and Claude Code are trademarks of Anthropic; PunkSolid is not affiliated. Confirm install steps and flags on code.claude.com before you automate anything.

What Claude Code is

Claude Code is Anthropic’s terminal-first coding agent: you work in a repository, prompt for changes, and receive git diffs. The quickstart covers installation and first commands; this page covers how we keep sessions safe on client and network repos.

For IDE-heavy teams, compare Claude Code vs Cursor and keep one verify command list for both tools.

1. Prepare the repository

Start with clean git status or explicit stash notes in your spec. Ambiguous dirty trees make it hard to separate agent edits from yours.

Run baseline tests locally so you know pre-agent green. If main is already failing, fix or document failures before you invite an agent.

Add or refresh AGENTS.md with verify commands your CI enforces. Agents should read it at session start; humans enforce it at merge time.

If you use Cursor rules for IDE work, ensure they do not contradict AGENTS.md paths and commands.

2. Write a narrow spec

Ask for a single vertical slice: one bug, one route, one migration phase—not “refactor the entire app.” Paste relevant file paths and link to acceptance criteria in spec-driven development.

List out of scope explicitly: lockfiles, unrelated packages, production env files, analytics IDs.

For URL or redirect work, attach the signed inventory from the website migration SEO checklist so the agent does not invent paths.

3. Start the session

Follow vendor install guidance from the quickstart. Work from the repository root unless AGENTS.md names a subdirectory project.

Give the agent read-only context first when exploring—then authorize edits. Narrow @ references beat dumping the whole monorepo.

State the verify command you will run after the agent claims done. PunkSolid defaults mirror methodology: agents propose; humans approve.

4. Review diffs like a human pull request

Read security-sensitive files first: authentication, payments, webhooks, PII handling, infra templates.

Re-run verify commands yourself—do not trust the agent’s summary of test output.

Reject drive-by formatting on unrelated modules. Mixed formatting obscures risky edits.

If the diff touches regulated marketing copy, schedule a human editorial pass even when code is correct.

5. Stop conditions

Pause or end the session when the agent:

• Edits lockfiles without your spec listing dependency changes
• Modifies CI workflows or deployment scripts without approval
• Touches secrets or suggests pasting API keys into rules
• Expands scope into directories marked off-limits in AGENTS.md

Resume only with an updated spec—not verbal permission in chat alone.

6. Merge and document

Use normal branch protection. Commit messages should explain why, especially when Claude Code generated most of the diff.

Update AGENTS.md or specs if the session revealed missing verify steps.

On client programs, align with code ownership handoff: future maintainers must understand which tasks you reserved for Claude Code vs Cursor.

Pairing with Cursor

Many PunkSolid engineers implement in Cursor and use Claude Code for a bounded batch (bulk renames, content generation after schema lock). The Cursor rules guide covers IDE governance; this tutorial covers terminal governance.

Use the same merge gate regardless of tool.

When to hire help

If sessions repeatedly blow scope or production incidents trace to agent edits, book AI code review or scoped Claude Code development with written acceptance tests.

General product work may fit website development when Claude Code is not the primary ask.

Practice project ideas

Safe learning exercises inside private repos:

• Fix a typed lint error in one package with tests
• Add one Astro or Next page following existing layout patterns
• Implement a redirect test for three URLs from an approved CSV

Avoid learning on production tenants or client orgs without permission.

Logging and retention

Follow your employer’s policy on storing agent transcripts. Some regulated environments require redaction or prohibition of cloud logging—set that in AGENTS.md before contractors use Claude Code.

Further reading

• AI coding agents compared — category map
• What is agentic AI? — concepts behind agents
• PunkSolid network build — quality gate in this repo

Cursor is a trademark of Anysphere, Inc., mentioned nominatively when describing mixed workflows.

Session sizing and timeboxing

Cap early sessions at 90 minutes and one merged outcome. Long unfocused chats encourage dependency drift and unrelated refactors. If the task is not done, write down blockers and start a new session with a narrower spec rather than extending chaos.

Use timers for exploration: ten minutes to read code, then edits. Exploration without bounds is how agents refactor files you never listed.

Working with tests and types

Ask the agent to run tests before you do, but never skip your own run. For typed stacks, ensure tsc or equivalent is in AGENTS.md. Agents may silence errors with any—reject that unless the spec allows temporary suppression with a ticket link.

On content repos, validate commands may include link or schema checks PunkSolid documents in methodology. Treat those like unit tests for copy.

Dependencies and supply chain

If the agent proposes new packages, require justification in the PR description and run your license allowlist process. Claude Code sessions can add transitive deps quickly.

Lockfile changes deserve their own spec section and human reviewer who owns release management.

Remote servers and SSH

Teams sometimes run Claude Code on remote boxes via SSH. Mirror AGENTS.md there; do not maintain divergent verify commands between laptop and server. Secrets on remote hosts still follow the same prohibition on pasting into chat.

Recovering from a bad session

Revert the branch, restore from stash, and write a postmortem bullet list: which paths were touched, which commands were skipped, which rule failed. Update AGENTS.md before retrying.

If damage reached production, prioritize rollback over finishing the feature. AI code review can help assess remaining risk after revert.

Coordinating with project management

Translate specs into tickets agents can reference by ID. PMs should not ask for “AI magic” without acceptance criteria—see spec-driven development.

Stakeholders read demos, not terminal scrollback. Export diffs or screen recordings when non-engineers sign off on UI.

Extending into production delivery

When tutorials are not enough—regulated industries, thousand-page migrations, commerce checkout—engage Claude Code development with written milestones. General marketing site work may fit website development without terminal-first requirements.