Claude Code: AI-Powered Development Workflow

For .NET engineers who know: Visual Studio IntelliSense, GitHub Copilot, and the general concept of AI-assisted code completion You’ll learn: How Claude Code — an autonomous terminal-based AI agent — differs from completion-based tools, and how to integrate it into daily development work Time: 15-20 min read

The .NET Way (What You Already Know)

GitHub Copilot inside Visual Studio or VS Code is the standard AI coding assistant in the .NET ecosystem. The model is familiar: you write code, Copilot suggests the next line or block, you accept or reject. IntelliSense fills in member names and signatures. ReSharper or the Roslyn analyzer gives you quick-fixes. Each of these is a reactive tool — it responds to your cursor position and suggests local completions.

When you need something bigger — generating a whole service class, understanding an unfamiliar codebase, writing a migration script — you probably switch to a chat interface (GitHub Copilot Chat, ChatGPT, or similar), copy-paste relevant code in, get a response, and copy-paste it back out. The workflow is manual. The AI has no direct access to your project. You are the bridge between the AI and the code.

This is the model Claude Code replaces.

The Claude Code Way

Claude Code is a terminal-based AI agent. You run it with claude from any directory, and it operates with direct access to your file system, your shell, and your project. It can read any file, write any file, run any command, and chain those operations across multiple steps — all within a single conversation.

The distinction from Copilot is architectural: Copilot is a completion engine. Claude Code is an agent. The difference matters in practice:

Installation and Setup

# Install Claude Code globally via npm
npm install -g @anthropic/claude-code

# Verify the installation
claude --version

# Start Claude Code in your project directory
cd /path/to/your/project
claude

After installation, Claude Code will prompt you to authenticate with your Anthropic account the first time you run it. Once authenticated, your credentials are stored and you do not need to authenticate again per session.

# Start Claude Code (opens an interactive session)
claude

# Start with an initial instruction
claude "explain how authentication works in this codebase"

# Run a one-shot task without entering interactive mode
claude -p "add JSDoc comments to all exported functions in src/services/"

The claude command opens an interactive REPL in your terminal. You type instructions, Claude Code reads files, writes code, runs commands, and reports results. You review the work and give further instructions.

The Conversation Model

Claude Code maintains a context window across a session. As you work, the context accumulates: files Claude Code has read, commands it has run, code it has written. This is different from a stateless chat interface — Claude Code remembers what it did five exchanges ago in the same session.

Practical implications:

• Start a new session (/clear or exit and restart) when switching to a completely different task. Accumulated context from a database migration task will confuse a UI component task.
• For large codebases, be explicit about scope. “Look at the auth module” is better than “look at everything.”
• Claude Code can request to read files, but it reads what you allow. On first use in a codebase, it will scan for a CLAUDE.md file (covered below) and use it as persistent context.

Common Workflows

Code Generation

The most common use case is generating new code that fits your existing patterns:

> Add a POST /api/invoices/:id/send endpoint. It should mark the invoice as sent,
  queue an email notification using our existing queue pattern (look at how
  /api/orders/:id/confirm works), and return the updated invoice.

Claude Code will:

1. Read the existing confirm endpoint and surrounding code
2. Understand the queue pattern from context
3. Write the new endpoint, service method, and any necessary types
4. Show you the diff before writing anything (configurable)

The key to good code generation is specificity. “Add a send endpoint” produces generic code. “Add a send endpoint following the confirm pattern” produces code that fits.

Debugging

Claude Code can investigate bugs across the full call stack without you copying stack traces into a chat:

> The POST /api/payments/webhook is returning 500 intermittently.
  The Sentry error id is PAYMENT-4521. Can you look at the handler,
  the relevant service code, and our Stripe webhook documentation
  link in the README, and tell me what's likely wrong?

Claude Code reads the handler, traverses to the service, checks the README, and provides an analysis. It can then propose a fix and apply it.

Refactoring

Large-scale refactors that would be tedious to do manually are where Claude Code earns its keep:

> We need to rename UserDto to UserResponseDto across the entire codebase.
  Find every usage, update the types, the imports, the controller return types,
  and the test assertions. Do not change the database schema or the API response
  shape — only the internal TypeScript name.

For a refactor touching 30 files, this is the difference between 20 minutes of careful search-and-replace and a few seconds of delegation.

Code Review

Before opening a PR, use Claude Code as a first-pass reviewer:

> Review the changes I've made in this branch for correctness, edge cases,
  and adherence to our patterns. Pay particular attention to the error
  handling and any place where I'm making assumptions about input shape.

Claude Code reads the diff (git diff main...HEAD), cross-references against the existing codebase, and produces a structured review. It catches things that automated linters miss: incorrect business logic, missing null checks in paths that reach the database, inconsistent error handling between similar endpoints.

Learning a New Codebase

When you join an existing project or start working in an unfamiliar area:

> Walk me through how a new user signs up. Start from the frontend form
  submission and trace through to the database insert. Explain each layer
  and what it's responsible for.

This is substantially faster than reading the code yourself. Claude Code traces the execution path, explains each component, and can answer follow-up questions. Think of it as having an onboarding session with the original author.

Slash Commands

Claude Code has built-in slash commands for common operations:

/help          # List all available commands
/clear         # Clear conversation context (start fresh)
/commit        # Stage and commit changes with a generated commit message
/review        # Review the current diff (equivalent to the review workflow above)
/cost          # Show token usage and estimated cost for the current session
/exit          # Exit Claude Code

The /commit command is worth calling out. When you’ve made a set of changes and want to commit:

> /commit

Claude Code will:

1. Run git diff --staged (and git diff if nothing is staged)
2. Generate a commit message that accurately describes the changes
3. Show you the message for approval
4. Stage the relevant files and commit

The generated messages are significantly better than generic “fix stuff” commits. They follow conventional commit format and describe the why, not just the what.

CLAUDE.md — Persistent Project Instructions

CLAUDE.md is a Markdown file you commit to the root of your repository. Claude Code reads it automatically at the start of every session. Think of it as the README.md that Claude Code reads instead of humans — it sets the context, conventions, and constraints for AI-assisted work on that project.

This is the equivalent of the “Project Structure” and “Development Guidelines” sections of a good README, but written specifically so an AI agent knows how to behave in your codebase.

Our team’s CLAUDE.md template:

# Project: [Project Name]

## Stack
- Runtime: Node.js 22, TypeScript 5.x
- Framework: [NestJS / Next.js / Nuxt]
- Database: PostgreSQL via Prisma
- Package manager: pnpm

## Architecture Overview
[2-3 sentences describing the main modules and their relationships]

## Key Conventions
- Services throw domain exceptions (`NotFoundException`, `ConflictException`)
  — controllers do not catch them
- All database access goes through Prisma service, never raw SQL
- DTOs use `class-validator` decorators for request validation
- Feature modules follow the pattern in `src/orders/` — use it as reference
- Environment variables are typed in `src/config/config.service.ts`
- Do not use `any` — use `unknown` and narrow, or define the type

## Testing
- Unit tests: Vitest, colocated with source files (`*.test.ts`)
- E2E tests: Playwright in `tests/e2e/`
- Run tests: `pnpm test`

## Branch and PR Conventions
- Branch naming: `feat/TICKET-123-short-description`, `fix/TICKET-123-description`
- All PRs require a passing CI run before merge
- Squash merge to main

## Commands
- `pnpm dev` — start development server
- `pnpm build` — production build
- `pnpm test` — run unit tests
- `pnpm lint` — ESLint check
- `pnpm db:migrate` — run pending Prisma migrations
- `pnpm db:studio` — open Prisma Studio

## Do Not
- Do not modify `prisma/schema.prisma` without also generating a migration
- Do not commit `.env` files
- Do not use `console.log` — use the Logger service
- Do not hardcode URLs — use the config service

When Claude Code reads this file, it knows how your project is structured before you give it any instructions. You spend less time explaining context and more time giving tasks.

Best Practices

Use Claude Code for tasks, not completions. If you need the next line of code, IntelliSense or Copilot is faster. Claude Code is for tasks that require reading context, making decisions across files, and producing a complete result.

Be specific about scope and constraints. “Refactor the auth system” is a bad instruction. “Extract the JWT validation logic from auth.service.ts into a separate jwt.service.ts, update the module registration, and leave the business logic unchanged” is a good instruction.

Review everything. Claude Code is genuinely good at understanding intent and pattern-matching across a codebase. It is not infallible. Review the diff it produces before accepting it, the same way you would review a PR from a junior engineer. The speed gains come from delegation, not from eliminating review.

Keep sessions focused. A session that wanders across multiple unrelated tasks accumulates context that becomes noise. A fresh session per logical task produces better results.

Write CLAUDE.md before you need it. Teams that skip the CLAUDE.md spend the first few instructions of every session re-explaining how the project works. Write it once; it pays dividends across every session from that point forward.

Know when not to use it. Simple edits, well-understood code, learning exercises — doing these yourself is faster and builds competence. Use Claude Code for tasks where the bottleneck is time, not understanding.

Key Differences

Gotchas for .NET Engineers

Gotcha 1: Claude Code Writes What You Describe, Not What You Mean

In Visual Studio, IntelliSense knows the exact type signatures in your project. When Copilot suggests code, it is constrained by what the compiler will accept. Claude Code operates on intent — it generates code based on what you describe and what it reads in context. If your description is ambiguous or your CLAUDE.md is missing key conventions, the output will be plausible but wrong in ways that compile cleanly.

Example: if you ask Claude Code to “add caching to the products endpoint” without specifying your caching infrastructure, it may implement an in-memory cache using a plain Map, when your team uses Redis via a shared CacheService. The fix is specificity: “add caching using our CacheService following the pattern in src/orders/orders.service.ts.”

This is not a limitation to work around — it is the correct mental model. Claude Code is a fast, capable colleague who needs clear requirements, not a compiler that enforces correctness.

Gotcha 2: The Context Window Is Not Unlimited

Claude Code can read a large amount of code in a session, but there is a limit. On very large codebases with many files read and many code changes made, the context approaches capacity. Signs that you are near the limit: Claude Code starts asking about things it already addressed earlier in the session, or its suggestions stop reflecting earlier constraints you established.

The fix is to start fresh sessions for distinct tasks and keep CLAUDE.md concise. The CLAUDE.md is always loaded at session start — it is your most reliable persistent context. Do not rely on information from earlier in a long session for complex, late-session tasks.

Gotcha 3: Claude Code Has No Access to External Systems Unless You Give It

Claude Code can read files and run terminal commands. It cannot access your Azure DevOps board, your Jira tickets, your Slack messages, or your database unless you provide credentials and tools for those systems. When you say “look at the ticket for context,” Claude Code cannot do that — you need to paste the relevant requirements into the conversation.

In practice, this means: paste the acceptance criteria, error messages, and relevant context directly into the session. Do not assume Claude Code can fetch it from somewhere. This is a deliberate security model — Claude Code operates in your shell environment with your credentials, and it explicitly does not reach out to services unless you invoke the relevant commands.

Gotcha 4: Generated Code Reflects the Context It Was Given

If the code Claude Code reads as reference examples has problems — inconsistent error handling, missing types, poor patterns — the generated code will reflect those problems. “Generate a new endpoint following this pattern” is only as good as the pattern. Claude Code amplifies whatever quality level it sees in the existing code.

This is actually useful as a diagnostic: if Claude Code consistently generates poor code for a particular part of your codebase, it is often a signal that the existing code in that area is not a good example to pattern-match against.

Gotcha 5: /commit Stages Files; Review Before Confirming

The /commit command will suggest staged files and a commit message. Confirm that the right files are included before accepting. It is easy to accidentally include debug files, temporary test scripts, or generated files that should be in .gitignore. Claude Code commits what is in your working tree, not necessarily what you intended to commit.

Establish a habit: after /commit proposes a commit, run git diff --staged to verify the contents before confirming.

Hands-On Exercise

Set up Claude Code on the project you are currently working on and complete the following tasks:

Task 1: Create your CLAUDE.md

Run claude in your project root and ask:

> Read the project structure and the main source files, then generate a CLAUDE.md
  file that documents the stack, key conventions, important commands, and things
  to avoid. Focus on what a developer would need to know to contribute effectively.

Review the output, correct any inaccuracies (Claude Code may guess at some conventions), and commit it.

Task 2: Use Claude Code for a real task

Pick a small, self-contained feature or bug fix you were planning to do anyway. Write it as an instruction in Claude Code instead of writing the code yourself. Review the output thoroughly.

Questions to answer after:

• Did Claude Code follow your existing patterns?
• What did you have to correct?
• What would have improved the initial instruction?

Task 3: Code review workflow

Make a small set of changes to your project — either the changes from Task 2 or a new set. Then:

> /review

Read the review. Did it catch anything you missed? Did it flag false positives? Use this to calibrate how you weigh Claude Code’s review feedback going forward.

Quick Reference

Session Commands

Instruction Patterns That Work

CLAUDE.md Sections (Team Standard)

# Project: [Name]
## Stack
## Architecture Overview
## Key Conventions
## Testing
## Branch and PR Conventions
## Commands
## Do Not

When to Use Claude Code vs. Code Manually

Further Reading

• Claude Code Documentation — Official documentation for installation, configuration, and all slash commands
• Anthropic Claude Code GitHub — Source, issues, and release notes
• CLAUDE.md Examples — Official guidance on writing effective CLAUDE.md files
• Claude Code Best Practices — Anthropic’s own engineering team’s usage patterns