02 - Claude Code: Agentic Development from Terminal
In the landscape of AI-assisted development tools, Claude Code occupies a unique position: it is an agentic CLI that lives in your terminal, reads your codebase, executes commands, modifies files, and manages complex workflows without ever opening an IDE. It is not a chatbot with code access: it is an autonomous agent that operates in your development environment with the same fluency a senior colleague would bring working alongside you.
This article is a comprehensive deep dive into Claude Code: from installation to advanced configuration, from internal architecture to practical workflows, from the permission system to creating custom agents. Whether you are an experienced developer looking to maximize productivity or a team lead evaluating agentic tools, here you will find everything needed to master this instrument.
What You Will Learn
- What Claude Code is and how it differs from traditional AI assistants
- Installation, configuration, and the
.claude/directory structure - Internal architecture: tool calling, context window, permission model
- All available tools: Read, Write, Edit, Bash, Grep, Glob, Task, WebSearch
- The permission system and the hooks mechanism
- How to write effective CLAUDE.md files to guide the agent's behavior
- Subagents, parallel execution, and isolation worktrees
- MCP (Model Context Protocol) integration for browsers, databases, and external services
- Practical workflows: TDD, code review, debugging, automated commits
- Comparison with Cursor, GitHub Copilot, and other IDE-based tools
- Best practices, known limitations, and workaround strategies
What Is Claude Code: The Agentic Paradigm in the Terminal
Claude Code is Anthropic's official CLI for agentic development. Unlike traditional chatbots where you copy and paste code between a chat window and your editor, Claude Code lives in your terminal with direct filesystem access: it can execute shell commands, read and modify files, search for patterns across the codebase, and orchestrate multi-step workflows without manual intervention.
The word agentic is essential to understanding this tool's nature. An AI agent does not merely answer questions: it acts. Claude Code analyzes the project context, plans the necessary changes, implements them through a series of tool calls, verifies the results, and iterates until the task is complete. It is the difference between asking someone "how do I do X?" and telling a competent collaborator "do X."
Chatbot vs Agent: The Fundamental Difference
A chatbot generates text in response to a prompt. An agent has access to tools and can take actions in the real world: reading files, executing commands, modifying code, browsing the web. Claude Code is an agent that operates in your development environment through a continuous cycle of observation-reasoning-action until the objective is achieved.
Claude Code is powered by the Claude model (currently Opus 4.6, Sonnet 4.6, and variants) and interfaces with the codebase through a set of native tools designed specifically for software development operations. In February 2026, GitHub integrated Claude Code into its Agent HQ platform, solidifying its role as the reference agent in the professional development ecosystem.
Installation and Configuration
Installing Claude Code is straightforward and requires Node.js 18+ and npm. The process involves three phases: package installation, authentication configuration, and environment customization.
Base Installation
# Global installation
npm install -g @anthropic-ai/claude-code
# Verify installation
claude --version
# First launch - opens browser for authentication
claude
# Or with direct API key
export ANTHROPIC_API_KEY=sk-ant-...
claudeOn first launch, Claude Code offers authentication via browser (OAuth) or direct API key. For personal use, the API key is sufficient; for teams and organizations, access through the Anthropic Console with centralized credential management is recommended.
The .claude/ Directory
After initialization, Claude Code creates a .claude/ directory in the project
root (and optionally in the user's home directory for global configurations). This directory
is the nerve center of the configuration.
.claude/
├── settings.json # Permission and tool configuration
├── agents/ # Custom agent definitions
│ ├── planner.md
│ ├── code-reviewer.md
│ └── security-reviewer.md
├── commands/ # Custom slash commands
│ └── review.md
├── hooks/ # Pre/post tool execution hooks
│ └── pre-commit-check.sh
├── rules/ # Behavior rules
│ └── coding-style.md
├── skills/ # Custom skills
│ └── angular-patterns.md
└── README.md # Local documentationThe settings.json File
The settings.json file controls permissions, authorized tools, and global
agent behavior. It is the first file to configure for a productive experience.
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Edit",
"Write",
"Bash(npm run lint)",
"Bash(npm run test)",
"Bash(npm run build)",
"Bash(git status)",
"Bash(git diff)",
"Bash(git log)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(git push --force)",
"Bash(git reset --hard)"
]
},
"alwaysThinkingEnabled": true,
"model": "claude-opus-4-6"
}Configuration Security
The deny section is critical for project safety. Blocking destructive
commands like rm -rf, git push --force, and
git reset --hard prevents accidental damage or damage caused by model
hallucinations. It is good practice to add any command that could cause irreversible
data loss to the deny list.
CLAUDE.md: Instructions for the Agent
The CLAUDE.md file is the heart of Claude Code customization. Placed in the
project root, it contains instructions that the agent reads automatically at every session.
Think of it as an onboarding document for a new team member: it describes
the project, conventions, architectures, and expectations.
Structure of an Effective CLAUDE.md
# CLAUDE.md
## Project Overview
This is an Angular 21 portfolio with SSR.
Stack: Angular 21, TypeScript 5.9, Express, Firebase Hosting.
## Architecture
- Standalone components (no modules)
- Signals for state management
- OnPush change detection
- Component-scoped CSS
## Coding Standards
- TypeScript strict mode
- Immutable data patterns
- File max 800 lines
- Functions max 50 lines
- kebab-case for files, PascalCase for classes
## Commands
- `npm start` - Dev server
- `npm run build` - Production build with SSR
- `npm test` - Run tests
- `npm run deploy` - Deploy to Firebase
## Important Patterns
- Each blog article = 4 files (IT/EN component + template)
- Registration in src/app/articles/index.ts
- Blog entries in src/app/services/blog.service.ts
- Angular templates: escape { } with HTML entities in code blocks
## Do NOT
- Do not modify Firebase configuration files
- Do not commit directly to main
- Do not use NgModules (standalone only)
- Do not use subscribe() - prefer async pipe or toSignal()A well-written CLAUDE.md dramatically reduces agent errors and improves output quality. The most important sections are: Project Overview (general context), Architecture (technical decisions), Coding Standards (conventions), and Do NOT (explicit constraints).
Rules Directory: Modular Rules
Beyond CLAUDE.md, Claude Code supports a .claude/rules/ directory where rules
can be organized by domain. This modular approach is preferable for complex projects.
# Coding Style Rules
## Immutability (CRITICAL)
ALWAYS create new objects, NEVER mutate existing ones.
Use spread operator, Object.assign(), or immutable libraries.
## File Organization
- Many small files > few large files
- 200-400 lines typical, 800 max
- Extract utilities from large modules
- Organize by feature/domain, not by type
## Error Handling
- Handle errors explicitly at every level
- Provide user-friendly messages in UI code
- Log detailed context server-side
- Never silently swallow errorsThe Memory System
Claude Code includes a persistent memory mechanism across sessions. The
MEMORY.md file in the .claude/ directory is automatically
updated by the agent with lessons learned during work sessions: discovered patterns,
common errors, project-specific configurations, and architectural decisions.
# Project Memory
## Angular Template Gotchas
- Curly braces in code blocks: wrap in ngNonBindable
AND escape { with { and } with }
- <T> generic types: escape < with < and > with >
- @ decorators in code: escape with @
## Blog Article Pattern
- Each article = 4 files: IT component + template, EN component + template
- Registration in src/app/articles/index.ts
- Blog entries in src/app/services/blog.service.ts
- Max ID: 288 (as of April 2026)Architecture and Internal Workings
Understanding how Claude Code works internally is essential for using it effectively. The architecture rests on three pillars: the agentic loop, the tool system, and context window management.
The Agentic Loop
When you send a message to Claude Code, the system enters a loop that repeats until the task is complete:
- Reception - The agent receives your message with all accumulated context
- Reasoning - The model analyzes the request and plans the necessary actions (extended thinking)
- Tool Call - The agent invokes one or more tools (Read, Edit, Bash, etc.)
- Observation - Tool results are added to the context
- Iteration - The model evaluates results and decides if further actions are needed
- Response - When the task is complete, the agent provides a summary
This loop can repeat dozens of times for a single complex task. For example, implementing a new feature might require: reading existing files (Read), searching for patterns (Grep/Glob), creating new files (Write), modifying existing files (Edit), running tests (Bash), fixing errors, and repeating.
Context Window Management
The context window is the amount of information the model can process in a single interaction. Claude Code manages context intelligently through several mechanisms:
- Selective loading - It does not load the entire codebase into memory. It uses Glob and Grep to find relevant files and Read to load only those that are needed.
- Automatic compaction - When the context approaches its limit, Claude Code compacts the conversation, retaining the most relevant information and discarding obsolete details.
- Subagents - For complex tasks requiring extensive context, Claude Code can delegate subtasks to subagents with isolated context (Task tool).
- Extended thinking - The model reserves up to 31,999 tokens for internal reasoning, separate from the conversation context.
Compaction: When and How It Happens
Compaction is the process by which Claude Code summarizes the conversation when the context grows too large. It is an automatic operation that preserves: CLAUDE.md instructions, architectural decisions made, modified files and their current state, and errors encountered. However, specific details from earlier iterations may be lost. For very long tasks, it is preferable to split the work into shorter, focused sessions.
The Core Tools
Claude Code comes with a set of native tools designed to cover the full spectrum of development operations. Each tool has a specific role and precise usage rules.
Reading and Search Tools
| Tool | Function | When to Use |
|---|---|---|
| Read | Reads the content of a specific file | When you know the exact file path |
| Glob | Searches for files by name pattern | To find files: **/*.ts, src/**/*.spec.ts |
| Grep | Searches for content within files | To find patterns, functions, classes across the codebase |
Writing and Editing Tools
| Tool | Function | When to Use |
|---|---|---|
| Write | Creates or overwrites an entire file | For new files or complete rewrites |
| Edit | Replaces specific portions of a file | For surgical changes to existing files |
Execution Tools
| Tool | Function | When to Use |
|---|---|---|
| Bash | Executes shell commands in the terminal | Build, test, git, npm, any CLI command |
| Task | Launches subagents with isolated context | For complex tasks requiring dedicated context |
Web and Search Tools
| Tool | Function | When to Use |
|---|---|---|
| WebSearch | Performs web searches | For documentation, updates, best practices |
| WebFetch | Downloads and analyzes URL content | For reading documentation, API references, articles |
Practical Example: Complete Tool Usage Cycle
# User asks: "Add a new 'priority' field to the Task model"
# 1. Claude Code searches for the existing model
Glob: src/app/models/**/*.ts
# Result: src/app/models/task.model.ts
# 2. Reads the model file
Read: src/app/models/task.model.ts
# Result: export interface Task { id: string; title: string; }
# 3. Modifies the model to add the field
Edit: src/app/models/task.model.ts
# old_string: "title: string;"
# new_string: "title: string;\n priority: 'low' | 'medium' | 'high';"
# 4. Searches for all files using the model
Grep: pattern "Task" in src/app/**/*.ts
# Result: 5 files found
# 5. Reads and updates every file that creates Task objects
# ... (Read + Edit cycle for each file)
# 6. Runs tests to verify
Bash: npm run test
# Result: 2 tests failed
# 7. Fixes the failing tests
# ... (Read + Edit cycle for tests)
# 8. Reruns tests
Bash: npm run test
# Result: All tests passedThe Permission System
Claude Code's permission system is designed around the principle of least privilege: the agent can only do what is explicitly authorized. This is critical for security, especially when the agent operates on production codebases.
The Three Permission Modes
| Mode | Behavior | Use Case |
|---|---|---|
| Allow | Tool executes without confirmation | Safe operations: file reading, searches |
| Ask | Claude Code asks for confirmation before executing | Default for most operations |
| Deny | Tool is completely blocked | Dangerous operations: delete, force push |
Permissions can be configured at three levels: global
(~/.claude/settings.json), project
(.claude/settings.json), and session (via the interactive
prompt). Project permissions override global ones, and session permissions override
project ones.
Granular Bash Permissions
The Bash tool supports granular permissions based on the specific command. This allows authorizing safe commands while maintaining blocks on dangerous ones.
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test)",
"Bash(npm run build)",
"Bash(git status)",
"Bash(git diff)",
"Bash(git log *)",
"Bash(git add *)",
"Bash(git commit *)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(git push --force *)",
"Bash(git reset --hard *)",
"Bash(git clean -f *)",
"Bash(git branch -D *)"
]
}
}The Defense-in-Depth Principle
Do not rely on permissions alone. Combine: (1) restrictive permissions in settings.json, (2) explicit instructions in CLAUDE.md about what NOT to do, (3) hooks that validate operations before execution, and (4) standard git hooks (pre-commit, pre-push) as the last line of defense. Security works in layers.
The Hooks System
Claude Code hooks are scripts that execute automatically before (PreToolUse) or after (PostToolUse) a tool invocation, or when the session ends (Stop). They are the most powerful mechanism for customizing and controlling agent behavior.
Hook Types
| Hook | When It Fires | Typical Use Case |
|---|---|---|
| PreToolUse | Before a tool executes | Parameter validation, conditional blocking, logging |
| PostToolUse | After a tool executes | Auto-formatting, linting, result verification |
| Stop | When the session ends | Final verification, cleanup, report generation |
Example: Auto-Formatting Hook
{
"hooks": {
"PostToolUse": [
{
"tool": "Edit",
"command": "npx prettier --write $CLAUDE_FILE_PATH",
"description": "Auto-format after every edit"
},
{
"tool": "Write",
"command": "npx prettier --write $CLAUDE_FILE_PATH",
"description": "Auto-format after file creation"
}
],
"PreToolUse": [
{
"tool": "Bash",
"command": "echo 'Executing: $CLAUDE_TOOL_INPUT'",
"description": "Log every Bash command"
}
],
"Stop": [
{
"command": "npm run lint",
"description": "Final lint before closing"
}
]
}
}
Hooks receive contextual information through environment variables like
$CLAUDE_FILE_PATH (the file being operated on) and
$CLAUDE_TOOL_INPUT (the tool parameters). This enables sophisticated
conditional logic.
Advanced Hook: Preventing Critical File Modifications
A PreToolUse hook can prevent modification of sensitive files (such as production
configurations or credential files) by verifying the file path before allowing the
Edit or Write operation. If the path matches a forbidden pattern (e.g.,
**/production.config.*), the hook returns an error and blocks the operation.
Agents and Subagents: Multi-Task Orchestration
One of Claude Code's most powerful capabilities is the Task tool, which allows launching subagents with isolated context. Each subagent operates in a separate "sandbox," with its own context, and returns results to the main process.
When to Use Subagents
- Independent parallel tasks - Simultaneously analyzing security, performance, and accessibility of a component
- Isolated context - When a subtask requires specific context that the main task does not need
- Multi-perspective analysis - Having the same code examined from different "perspectives" (security expert, performance engineer, UX reviewer)
- Long-running tasks - Delegating lengthy operations while the main process continues with other work
Example: Multi-Perspective Code Review
# Prompt to the main task:
"Do a complete code review of the component
src/app/components/payment-form/"
# Claude Code launches 3 subagents in parallel:
# Subagent 1: Security Review
Task: "Analyze the payment-form component for
security vulnerabilities: XSS, injection,
sensitive data handling, CSRF."
# Subagent 2: Performance Review
Task: "Analyze the performance of the payment-form
component: change detection, memory leaks,
rendering optimization, lazy loading."
# Subagent 3: Accessibility Review
Task: "Verify the accessibility of the payment-form
component: ARIA labels, keyboard navigation,
focus management, color contrast."
# The 3 results are combined in the final reportCustom Agents
The .claude/agents/ directory allows defining specialized agents with
specific instructions and personas. Each Markdown file in this directory becomes an
invocable agent.
# Code Reviewer Agent
## Role
You are a senior code reviewer with 15 years of experience.
You are rigorous but constructive.
## Review Checklist
For each file analyzed, verify:
1. Naming: variables, functions, and classes have clear names
2. Complexity: no function > 50 lines
3. Immutability: no state mutation
4. Error handling: all errors handled
5. Types: no `any`, specific types everywhere
6. Security: inputs validated, no hardcoded data
## Output Format
Classify each issue found:
- CRITICAL: bug or vulnerability (blocks merge)
- HIGH: architectural problems (must resolve)
- MEDIUM: quality improvements (recommended)
- LOW: style suggestions (optional)Isolation Worktrees
For tasks requiring experimental changes without risking the current branch, Claude Code
supports git worktrees. The EnterWorktree tool creates an isolated
worktree in .claude/worktrees/ with a new branch based on HEAD. At the end
of the session, the user can choose to keep or remove the worktree.
MCP Integration: Model Context Protocol
The Model Context Protocol (MCP) is an open standard that enables Claude Code to communicate with external services through MCP servers. This enormously extends the agent's capabilities beyond the local filesystem.
MCP Architecture
The MCP architecture follows a client-server model where Claude Code acts as the client and MCP servers expose additional tools. An MCP server can provide access to: web browsers, databases, external APIs, cloud services, CI/CD systems, and much more.
Common MCP Use Cases
| MCP Server | Capability | Example Use |
|---|---|---|
| Browser Automation | Web navigation, clicks, screenshots, form filling | E2E testing, scraping, workflow automation |
| Database | SQL/NoSQL queries, schema exploration | Data debugging, schema migration |
| GitHub | PRs, issues, code review, actions | GitHub workflow automation |
| Figma | Design reading, component extraction | Code generation from designs |
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["@anthropic-ai/claude-code-mcp-browser"],
"description": "Browser automation server"
},
"postgres": {
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
}
}
}
}MCP and Security
Each MCP server has access to the resources configured for it. A database server has access to the database; a browser server can browse the web. It is essential to apply the least privilege principle to MCP servers as well: use read-only credentials where possible, limit access to development databases, and never expose production credentials.
Skills and Custom Commands
Claude Code's Skills system allows defining specialized capabilities that the agent can invoke during sessions. Unlike agents (which define persona and approach), skills define specific procedures for recurring tasks.
Custom Slash Commands
Slash commands are shortcuts invocable with /commandname syntax during a
session. They are defined as Markdown files in the .claude/commands/
directory.
# /review Command
Run a complete code review of files modified
in the last commit.
## Steps
1. Run `git diff HEAD~1` to get the changes
2. For each modified file:
a. Read the complete file for context
b. Analyze changes for:
- Potential bugs
- Coding standard violations
- Security issues
- Improvement opportunities
3. Generate a report with severity levels:
CRITICAL, HIGH, MEDIUM, LOW
4. Suggest specific fixes for CRITICAL and HIGH issuesCustom Skills
Skills in the .claude/skills/ directory are more elaborate than commands
and can include technical context, examples, and multi-step procedures.
# Angular Blog Article Creation Skill
## Context
This project uses Angular 21 with blog articles
that require 4 files per article (IT + EN).
## Procedure
1. Create TypeScript component (IT):
src/app/articles/{series}/{name}.component.ts
2. Create HTML template (IT):
src/app/articles/{series}/{name}.component.html
3. Create TypeScript component (EN):
src/app/articles/{series}/{name}.en.component.ts
4. Create HTML template (EN):
src/app/articles/{series}/{name}.en.component.html
5. Register in src/app/articles/index.ts
6. Add BlogPost entry in blog.service.ts
## Template Rules (CRITICAL)
- Escape { } in code blocks with HTML entities
- Wrap code blocks in ngNonBindable
- Escape <T> generics with < >
- Escape @ decorators with @Practical Workflows with Claude Code
Theory is important, but the real value of Claude Code emerges in daily workflows. Let us explore how to use it for the most common software development tasks.
1. Test-Driven Development (TDD)
# Prompt:
"Implement a UserService using TDD.
It should support: getById, create, update, delete.
Use the Repository pattern for data access."
# Claude Code:
# 1. Creates tests BEFORE implementation (RED)
Write: src/app/services/user.service.spec.ts
# Tests for getById, create, update, delete
# 2. Runs the tests - they should FAIL
Bash: npm run test -- --filter=UserService
# Result: 4 tests FAILED (as expected)
# 3. Implements the service (GREEN)
Write: src/app/services/user.service.ts
# Minimal implementation to pass the tests
# 4. Runs the tests - they should PASS
Bash: npm run test -- --filter=UserService
# Result: 4 tests PASSED
# 5. Refactoring (IMPROVE)
Edit: src/app/services/user.service.ts
# Improves structure while keeping tests green
# 6. Verifies coverage
Bash: npm run test -- --coverage2. Interactive Debugging
# Prompt:
"The Dashboard component does not render data.
The console shows 'Cannot read properties of undefined'.
Find and fix the bug."
# Claude Code:
# 1. Searches for the component
Glob: src/**/dashboard*
# 2. Reads the component and template
Read: src/app/components/dashboard/dashboard.component.ts
Read: src/app/components/dashboard/dashboard.component.html
# 3. Searches for the service providing data
Grep: pattern "DashboardService" in src/
# 4. Reads the service
Read: src/app/services/dashboard.service.ts
# 5. Identifies the problem: the API response has
# a different structure than expected
# 6. Fixes the data mapping
Edit: src/app/services/dashboard.service.ts
# 7. Adds null check in the template
Edit: src/app/components/dashboard/dashboard.component.html
# 8. Verifies the build
Bash: npm run build3. Automated Commit Workflow
Claude Code has a built-in workflow for creating Git commits that analyzes changes, generates a descriptive message, and handles file staging.
# Prompt:
"Commit the current changes"
# Claude Code:
# 1. Analyzes repository state
Bash: git status
Bash: git diff
Bash: git log --oneline -5
# 2. Identifies relevant files to commit
# 3. Adds specific files (never git add -A)
Bash: git add src/app/services/user.service.ts
Bash: git add src/app/services/user.service.spec.ts
# 4. Creates commit with descriptive message
Bash: git commit -m "feat: add UserService with
Repository pattern and full CRUD operations"
# 5. Verifies the result
Bash: git status4. Guided Refactoring
# Prompt:
"The file src/app/components/mega-form.component.ts
has 1200 lines. Decompose it into smaller components
following the Single Responsibility Principle."
# Claude Code:
# 1. Analyzes the monolithic file
Read: src/app/components/mega-form.component.ts
# 2. Identifies distinct responsibilities
# 3. Creates separate components:
Write: src/app/components/form-header/form-header.component.ts
Write: src/app/components/form-fields/form-fields.component.ts
Write: src/app/components/form-validation/form-validation.component.ts
Write: src/app/components/form-submit/form-submit.component.ts
# 4. Updates the original component as orchestrator
Edit: src/app/components/mega-form.component.ts
# 5. Updates the tests
# 6. Verifies build and tests
Bash: npm run build && npm run testClaude Code vs Cursor vs GitHub Copilot
Choosing the right tool depends on context, task type, and personal preferences. Claude Code, Cursor, and GitHub Copilot are not mutually exclusive alternatives: they are complementary.
| Aspect | Claude Code | Cursor | GitHub Copilot |
|---|---|---|---|
| Interface | CLI / Terminal | IDE (VS Code fork) | IDE Plugin |
| Mode | Agentic (autonomous) | Agentic + inline | Assistant + agentic |
| Autonomy | High (autonomous loops) | Medium-High | Medium |
| Context | Full filesystem | Open project | Open files + index |
| Tool execution | Full shell | Integrated terminal | Limited |
| MCP Support | Native | Supported | Via extensions |
| Customization | CLAUDE.md + rules + hooks | .cursorrules | Copilot instructions |
| Best for | Complex tasks, automation, CI/CD | Daily development | Completion, snippets |
| Cost | Pay-per-use (API) or Max plan | $20/month Pro | $10-19/month |
When to Use Which Tool
- Claude Code - Complex end-to-end tasks (implement a complete feature, refactor across 20 files, configure CI/CD), terminal operations, workflow automation, working on remote servers via SSH.
- Cursor - Daily development, interactive editing, when you want to see changes in real time in the editor, AI pair programming, rapid prototyping.
- GitHub Copilot - Fast autocompletion while writing, quick snippet generation, when you are already in a coding flow and want inline suggestions.
The most productive combination for many developers is: Cursor for daily interactive development, Copilot for rapid inline completion, and Claude Code for complex tasks, automation, and terminal operations. These tools operate at different levels and complement each other.
Best Practices for Effective Use
After months of intensive Claude Code usage on real projects, here are the practices that make the difference between a frustrating experience and a highly productive one.
1. Write a Detailed CLAUDE.md
The CLAUDE.md is the investment with the highest ROI. A well-written file reduces agent errors by an estimated 50-70%. Always include: project overview, technology stack, coding conventions, build/test commands, architectural patterns, and an explicit "Do NOT" section with constraints.
2. Use Specific, Contextual Prompts
# VAGUE (unpredictable result):
"Improve the form component"
# SPECIFIC (predictable result):
"In the component src/app/components/contact-form/:
1. Add email validation with regex
2. Add optional phone field
3. Show inline errors below each field
4. Use Angular reactive forms pattern
5. Maintain existing CSS styling"3. Work in Focused Sessions
Avoid overly long sessions that lead to context compaction. Prefer 15-30 minute sessions focused on a single objective. When the task is complex, break it into subtasks and tackle them in separate sessions.
4. Always Verify the Build
After every cycle of significant changes, ask Claude Code to run the build and tests. Do not assume modifications are correct: the model can make subtle errors that only surface at compile time or runtime.
5. Use the Rules System for Complex Projects
For projects with many conventions, use the .claude/rules/ directory with
separate files per domain: coding-style.md, security.md,
testing.md, git-workflow.md. This is more maintainable than a
single monolithic CLAUDE.md.
6. Configure Hooks for Automation
PostToolUse hooks for auto-formatting (Prettier, ESLint) eliminate an entire category of style errors. PreToolUse hooks for validation prevent dangerous operations. Investing 10 minutes in hook configuration saves hours of manual corrections.
Limitations and Workarounds
Claude Code is not perfect. Understanding its limitations is fundamental to managing expectations and adopting mitigation strategies.
Limitation 1: Context Window
The context has a fixed limit. For very large projects, the model cannot "see" the entire codebase simultaneously. Automatic compaction helps but can lose important details.
Workaround: Break tasks into focused subtasks. Use CLAUDE.md to provide architectural context that does not require reading files. Use subagents (Task tool) to delegate parallel analysis.
Limitation 2: Hallucinations
The model can generate code that appears correct but contains subtle logic errors, references to nonexistent APIs, or patterns not supported by a specific framework version.
Workaround: Always verify with build and tests. Specify exact framework versions in CLAUDE.md. When working with external APIs, provide documentation via WebFetch or attach working examples.
Limitation 3: Interactive Operations
Claude Code cannot handle interactive commands that require keyboard input (such as
git rebase -i or confirmation prompts). Commands must be non-interactive.
Workaround: Use non-interactive flags where available (-y,
--yes). For git, use specific commands instead of interactive ones.
Limitation 4: Binary Files and Images
Claude Code can read images (it is multimodal) but cannot generate or modify binary files such as images, videos, or PDFs.
Workaround: For image operations, use CLI tools like ImageMagick or ffmpeg through the Bash tool.
Limitation 5: Cost
API-based usage can become expensive for long, intensive sessions. Each agentic loop consumes tokens both for reasoning and tool results.
Workaround: Use the Max plan for a fixed monthly cost if usage is frequent. Optimize prompts to be specific (fewer iterations). Use subagents to parallelize where possible (faster means fewer total tokens).
Common Mistake: Blindly Trusting Output
The most frequent mistake with Claude Code is accepting all output without verification. The model can: create files in wrong directories, use incorrect imports, introduce regressions in files not directly related to the change, or generate code that compiles but has logic bugs. Always verify with build and tests. Pure vibe coding is for prototypes; production code demands human review.
Conclusions
Claude Code represents a qualitative leap in how developers interact with AI. It is not simply a chatbot that suggests code: it is an autonomous agent that operates in your development environment, understands the project context, and can manage complex end-to-end tasks.
The tool's power emerges from the combination of: direct filesystem and shell access, a granular permission system, hooks for custom automation, subagents for parallel tasks, and MCP integration for extending capabilities beyond the local codebase. All of this controlled by a CLAUDE.md file that functions as a briefing for an expert collaborator.
But power comes with responsibility. Claude Code works best when the developer maintains an active role as supervisor and orchestrator: defining clear objectives, configuring appropriate guardrails, verifying results, and intervening when necessary. It is not a "set and forget" tool: it is a productivity multiplier for those who know how to guide it.
Next Articles in the Series
- 03 - Agentic Workflows: How to decompose complex problems for AI agents, multi-step orchestration, and effective delegation patterns
- 04 - Multi-Agent Systems: Collaboration architectures between agents, communication protocols, and enterprise use cases
- 05 - Testing AI-Generated Code: TDD strategies, property-based testing, and quality validation for AI-generated code
Key Takeaways
- Claude Code is an agentic CLI that operates in the terminal with access to the filesystem, shell, and development tools
- CLAUDE.md is the highest-ROI investment: it guides the agent's behavior and reduces errors by an estimated 50-70%
- The permission system (allow/ask/deny) implements the least privilege principle to protect the codebase
- PreToolUse/PostToolUse hooks automate validation and formatting
- Subagents (Task tool) enable parallel execution and multi-perspective analysis
- MCP extends agent capabilities to browsers, databases, and external services
- Claude Code, Cursor, and Copilot are complementary, not alternatives
- Always verify with build and tests: pure vibe coding is for prototypes, production demands human oversight
- Short, focused sessions (15-30 minutes) produce better results than long, generic ones