Building AI Agents for Beginners: Your First Autonomous Workflow

Commands are powerful. You run /commit, Claude creates a commit. You run /review, Claude reviews code. But what if Claude could chain these actions together, make decisions, and complete complex workflows without constant direction?

That's what agents do. They're autonomous workflows that observe, think, and act—handling multi-step processes that would otherwise require your constant attention.

This guide introduces you to agent development. You'll understand what makes agents different from commands, learn the core patterns, and build your first working agent.

Understanding AI Agents

What Makes an Agent?

An agent is more than a script that runs commands sequentially. Agents have three defining characteristics:

1. Autonomy Agents make decisions without constant human input. A command does exactly what you tell it. An agent decides what to do based on context.

2. Goal-Orientation Agents work toward objectives, not just tasks. A command completes a single task. An agent pursues a goal that might require many tasks.

3. Adaptability Agents respond to changing conditions. A command follows a fixed path. An agent adjusts its approach based on what it discovers.

The Agent Loop

Every agent follows a fundamental cycle:

Observe → Think → Act → Observe → Think → Act → ...

Observe: Gather information about current state Think: Analyze the situation and decide next action Act: Execute the chosen action Repeat: Continue until goal is achieved

This loop continues until the agent either achieves its goal or determines it cannot proceed.

Commands vs. Agents

Agent Architecture in Claude Code

Agent File Structure

Agents live in .claude/agents/ with this structure:

---
description: What this agent does
trigger: When this agent activates (optional)
tools: What capabilities this agent has
---

# Agent Name

## Objective
The goal this agent pursues.

## Capabilities
What this agent can do.

## Decision Framework
How this agent makes decisions.

## Execution Process
The steps this agent follows.

## Termination Conditions
When this agent stops.

The Trigger System

Agents can be triggered in two ways:

Manual: User explicitly invokes the agent

/agent:cleanup

Automatic: Agent activates based on conditions

---
trigger:
  event: pre-commit
  condition: "staged files include test changes"
---

Tool Access

Agents need tools to act on the world. Common tools:

• File System: Read, write, search files
• Shell: Execute commands
• Git: Version control operations
• Network: API calls (when allowed)

You define available tools in the frontmatter:

---
tools:
  - filesystem
  - shell
  - git
---

Building Your First Agent: The Cleanup Agent

Let's build an agent that cleans up a codebase. This agent will:

1. Find unused imports
2. Remove dead code
3. Fix formatting issues
4. Create a summary of changes

Step 1: Create the Agent File

mkdir -p .claude/agents
touch .claude/agents/cleanup.md

Step 2: Write the Frontmatter

---
description: Autonomously clean up codebase issues
version: 1.0.0
tools:
  - filesystem
  - shell
  - git
---

Step 3: Define the Objective

# Cleanup Agent

## Objective

Clean up the codebase by finding and fixing common code quality issues. Work autonomously through the codebase, making improvements while preserving functionality.

**Success criteria:**
- No unused imports remain
- No obvious dead code
- Consistent formatting
- All changes are safe (no functionality altered)

Step 4: Define Capabilities

## Capabilities

This agent can:
- Read and analyze source files
- Detect unused imports and dead code
- Run linting and formatting tools
- Make safe, targeted edits
- Commit changes with clear messages

This agent cannot:
- Modify business logic
- Delete files
- Change function signatures
- Modify configuration files without confirmation

Step 5: Build the Decision Framework

This is where agents differ most from commands. The agent needs rules for making decisions:

## Decision Framework

### What to Clean

**Unused Imports**
- Import is declared but never referenced
- Import is referenced only in deleted code
- ACTION: Remove the import line

**Dead Code**
- Functions never called from anywhere
- Variables assigned but never read
- Unreachable code after return/throw
- ACTION: Remove if confident, flag if uncertain

**Formatting Issues**
- Inconsistent indentation
- Missing semicolons (if project uses them)
- Trailing whitespace
- ACTION: Fix automatically

### What NOT to Touch

- Commented code with TODO/FIXME markers
- Imports that might be used dynamically
- Code that looks dead but is referenced in tests
- Any file in .gitignore or node_modules

### Uncertainty Handling

When uncertain whether code is dead:
1. Search for usages across the entire codebase
2. Check if it's exported (might be used externally)
3. Check if it's documented in README/API docs
4. If still uncertain, skip and add to report

**Rule:** When in doubt, don't delete.

Step 6: Define the Execution Process

## Execution Process

### Phase 1: Discovery

1. List all source files in the project
2. Identify the primary language(s)
3. Check for existing linting configuration
4. Note any .gitignore patterns

### Phase 2: Analysis

For each source file:
1. Parse imports/requires
2. Build a list of all symbols used
3. Compare imports to usage
4. Identify unused imports
5. Look for dead code patterns

### Phase 3: Planning

1. Compile list of all proposed changes
2. Group by file and type
3. Estimate risk level of each change
4. Prioritize safe, high-impact changes

### Phase 4: Execution

For each file with changes:
1. Read current content
2. Apply changes (lowest risk first)
3. Verify file still parses correctly
4. Stage the file

### Phase 5: Verification

1. Run linter (if available)
2. Run tests (if available and quick)
3. If any check fails, revert last change
4. Continue with remaining changes

### Phase 6: Completion

1. Create commit with detailed message
2. Generate summary report
3. List any issues that need manual review

Step 7: Define Termination Conditions

## Termination Conditions

### Success Termination
- All files processed
- All safe changes applied
- Tests pass (if available)
- Summary generated

### Early Termination

Stop immediately if:
- More than 10 files would be modified (ask for confirmation)
- Any tests fail after changes
- A change causes syntax errors
- User sends interrupt signal

### Reporting

On termination, always provide:

Cleanup Summary

Files analyzed: X Files modified: Y Unused imports removed: Z Dead code removed: N lines Issues flagged for review: M

Details:

• file1.js: Removed 3 unused imports
• file2.py: Removed unused function 'oldHelper'
• file3.ts: Flagged 'maybeUsed()' for review

Complete Agent File

Here's the complete agent for reference:

---
description: Autonomously clean up codebase issues
version: 1.0.0
tools:
  - filesystem
  - shell
  - git
---

# Cleanup Agent

## Objective
[Content from Step 3]

## Capabilities
[Content from Step 4]

## Decision Framework
[Content from Step 5]

## Execution Process
[Content from Step 6]

## Termination Conditions
[Content from Step 7]

Testing Your Agent

Step 1: Create a Test Environment

Don't test agents on important code. Create a test project:

mkdir agent-test && cd agent-test
git init

# Create files with issues
cat > example.js << 'EOF'
import { unused } from 'lodash';
import { used } from './utils';
import { alsoUnused } from './helpers';

function activeFunction() {
  return used('hello');
}

function deadFunction() {
  console.log('I am never called');
}

function anotherDead() {
  return 'also never called';
}

export { activeFunction };
EOF

cat > utils.js << 'EOF'
export function used(x) {
  return x.toUpperCase();
}

export function unused() {
  return 'nobody uses me';
}
EOF

Step 2: Run the Agent

claude

Then:

/agent:cleanup

Step 3: Observe Behavior

Watch how the agent:

1. Discovers the files
2. Analyzes imports and usage
3. Identifies the dead code
4. Makes decisions about what to remove
5. Reports its findings

Step 4: Verify Results

After the agent completes:

git diff HEAD~1  # See what changed
git log -1       # See commit message

Common Agent Patterns

Pattern 1: The Scout-Execute Pattern

First gather all information, then act:

## Execution Process

### Scout Phase
1. Analyze entire codebase
2. Build complete picture
3. DO NOT modify anything yet

### Execute Phase
1. Based on scout findings
2. Apply changes systematically
3. Verify each change

Pattern 2: The Checkpoint Pattern

Create safe points to roll back to:

## Safety Checkpoints

After every 5 file modifications:
1. Run verification tests
2. If passing, create checkpoint commit
3. If failing, rollback to last checkpoint
4. Report issue and continue with remaining files

Pattern 3: The Escalation Pattern

Escalate decisions based on risk:

## Decision Escalation

### Automatic (no confirmation needed)
- Removing definitely unused imports
- Fixing whitespace
- Sorting imports

### Confirm Before Proceeding
- Removing functions (might be called dynamically)
- Deleting files
- Modifying exports

### Never Do Automatically
- Changing business logic
- Modifying security-related code
- Altering API contracts

Debugging Agents

Agent Logs

Add logging instructions to your agent:

## Logging

Throughout execution, log:
- Current phase
- File being processed
- Decisions made and why
- Any uncertainties encountered

Format:
[PHASE] message
[DECISION] chose X because Y
[UNCERTAIN] about Z, skipping

Step-by-Step Mode

For debugging, add a step mode:

## Debug Mode

If user runs `/agent:cleanup --debug`:
- Pause after each decision
- Show what you're about to do
- Wait for confirmation before proceeding
- Show reasoning at each step

Dry Run Mode

Test without making changes:

## Dry Run Mode

If user runs `/agent:cleanup --dry-run`:
- Go through entire process
- DO NOT make any actual changes
- Report what WOULD have been changed
- Useful for testing and verification

Best Practices for Agent Development

Start Simple

Your first agents should be:

• Limited in scope
• Conservative in actions
• Verbose in reporting

Expand capabilities only after basic version works reliably.

Fail Safe

Agents should default to caution:

• When uncertain, don't act
• When risky, ask for confirmation
• When failing, rollback cleanly

Provide Transparency

Users should understand what agents do:

• Log decisions clearly
• Explain reasoning
• Summarize all changes

Limit Blast Radius

Constrain what agents can affect:

• Limit files per run
• Require confirmation for bulk changes
• Create checkpoints for rollback

Test Extensively

Test agents on:

• Empty projects
• Projects with errors
• Large projects
• Projects with unusual structures

Next Steps

You've built your first agent. Here's where to go next:

More Agent Types to Build

• Test Agent - Automatically write tests for new code
• Review Agent - Review PRs and suggest improvements
• Refactor Agent - Identify and execute refactoring opportunities
• Doc Agent - Keep documentation in sync with code

Advanced Topics

• Multi-agent coordination
• Long-running agents
• Agent memory and learning
• Integration with external services

Resources

• MCP Server Setup Tutorial - Connect agents to external tools
• Workflow Automation - Chain agents into workflows
• AI Agents Guidebook - Deep dive into agent theory

Summary

Agents extend Claude Code from task execution to goal pursuit. They observe, think, and act autonomously—handling complex workflows that would otherwise require constant human direction.

Key concepts:

• Autonomy: Agents make decisions
• Goals: Agents pursue objectives
• Adaptability: Agents respond to conditions
• The Loop: Observe -> Think -> Act -> Repeat

Your cleanup agent demonstrates these principles in action. Use it as a template for building more sophisticated agents that automate your development workflow.

---

Ready to connect your agents to external services? Learn MCP Server Setup to expand what your agents can do.