Best Practices for AI Code Agents

The right mindset

AI code agents are not autocomplete on steroids. They're autonomous collaborators that can read files, run commands, make decisions, and iterate on solutions. To work effectively with them:

• Think in outcomes, not steps: Describe what you want to achieve, not how to achieve it. Let the agent figure out the path.
• Trust but verify: Agents make mistakes. Review their work, especially for security-sensitive code.
• Iterate fast: If something isn't working, interrupt and redirect. Don't wait for a long task to fail.
• Provide context, not instructions: The more the agent understands about your codebase and goals, the better it performs.

Plan before you build

The single most impactful practice is planning before coding. Ask the agent to research your codebase, identify dependencies, and propose implementation strategies before writing a single line of code.

When to request a plan

• Adding new features that touch multiple files
• Refactoring existing systems
• Working in unfamiliar codebases
• Tasks where architecture decisions matter

How to request planning

# Ask the agent to plan before implementing
"Before implementing anything, create a detailed plan for adding user authentication"

# Or be explicit about exploring first
"Explore the codebase and understand how payments work before making any changes"

# For complex tasks, use auto-mode with checkpoints
autohand --auto-mode --checkpoint-interval 5

What good plans include

• Files that need to be created or modified
• Dependencies and their order
• Potential risks or breaking changes
• Testing strategy

Review the plan, ask questions, and only approve when you're confident in the approach. This upfront investment saves hours of debugging later.

Context management

Agents perform better with the right context. Too little context leads to wrong assumptions. Too much context wastes tokens and slows responses. Autohand provides several ways to manage context effectively.

AGENTS.md files

Create an AGENTS.md file in your project root to provide persistent context about your codebase. Autohand automatically reads this file at the start of each session.

# AGENTS.md

## Project Overview
This is a Next.js 14 application using the App Router, TypeScript, and Prisma ORM.

## Architecture
- `/app` - Next.js App Router pages and layouts
- `/lib` - Shared utilities and database client
- `/components` - React components with shadcn/ui

## Code Style
- Use TypeScript strict mode
- Prefer server components where possible
- Use Zod for runtime validation

## Commands
- `bun run dev` - Start development server
- `bun run test` - Run tests
- `bun run db:push` - Push schema changes

Initialize with /init

Use the /init command to generate an AGENTS.md file based on your project structure:

# Generate AGENTS.md for your project
/init

# The agent will analyze your codebase and create appropriate context

Skills for domain-specific knowledge

Use skills to package domain-specific knowledge that agents can invoke when needed.

# List available skills
/skills

# Skills are automatically discovered from:
# - .autohand/skills/
# - ~/.autohand/skills/
# - Project-specific skill directories

# Enable automatic skill detection
autohand --auto-skill

Fresh conversations

Start new conversations when switching tasks. Context from unrelated tasks can confuse agents and lead to incorrect solutions.

# Start a fresh session
/new

# Or manage sessions explicitly
/sessions          # List all sessions
/session my-task   # Switch to a named session
/resume            # Resume last session

Add context directories

# Add additional directories to context
/add-dir ./libs/shared

# Useful when working across multiple packages

Effective prompting

How you communicate with agents matters. Clear, specific prompts lead to better results.

Be specific about scope

Provide acceptance criteria

Tell the agent what success looks like:

Add a password reset feature. It should:
- Send an email with a reset link
- Links expire after 1 hour
- Users can't reuse their last 3 passwords
- Log all reset attempts for security audit
- Work with our existing email service in lib/email.ts

Use constraints

Constraints help agents make better decisions:

Refactor the authentication module. Constraints:
- Don't change the public API
- Keep backward compatibility with existing tokens
- No new dependencies
- Must pass all existing tests

Test-driven development

Tests are the best way to verify agent work. They provide clear success criteria and catch regressions automatically.

Write tests first

1. Write a failing test for the feature
2. Ask the agent to make it pass
3. Review the implementation
4. Add edge case tests
5. Have the agent handle edge cases

Use tests as specifications

# Point the agent to tests
"Make all tests in tests/payment.test.ts pass"

# Or run tests as part of verification
"After implementing the feature, run the test suite and fix any failures"

Use linting and formatting

Autohand includes built-in support for code quality checks:

# Check linting issues
/lint

# Configure formatters
/formatters

# Ask the agent to fix issues
"Fix all linting errors in the codebase"

Typed languages help

TypeScript, Go, Rust, and other typed languages provide compile-time verification. Type errors give agents immediate feedback on mistakes.

# Have the agent fix type errors
"Fix all TypeScript errors in the codebase"

# Use strict mode for better error detection
# tsconfig.json: "strict": true

Review strategies

Agent output needs review. The goal is to catch issues without creating bottlenecks.

Watch in real-time

Monitor agent progress as it works. If you see it heading in the wrong direction, interrupt early:

# Press Ctrl+C to interrupt
# Then redirect
"Stop. That approach won't work because of X. Instead, try Y."

Use diff review

After agents make changes, review the diff before committing:

# Review changes with git
git diff

# Ask the agent to explain changes
"Explain the changes you made to the authentication module"

# Undo the last change if needed
/undo

Commit with context

Use the built-in commit command for well-formatted commits:

# Create a commit with agent-generated message
/commit

# The agent will analyze changes and create an appropriate commit message

Automated checks with hooks

Set up hooks to run checks automatically after agent actions:

# View available hooks
/hooks

# Hooks can trigger on events like:
# - before_tool_call
# - after_tool_call
# - on_file_change
# - on_error

Automation workflows

Autohand excels at automating repetitive tasks. Use auto-mode and skills for common operations.

Auto-mode for autonomous operation

Auto-mode lets the agent work autonomously with git worktree isolation:

# Enable auto-mode for autonomous operation
autohand --auto-mode

# Configure iteration limits
autohand --auto-mode --max-iterations 50

# Set checkpoint intervals for long tasks
autohand --auto-mode --checkpoint-interval 10

# Toggle auto-mode during a session
/automode

Non-interactive mode

Run agents without interaction for automation pipelines:

# Run with automatic yes to prompts
autohand -y --prompt "Update all dependencies and fix any breaking changes"

# Use in CI/CD pipelines
autohand --yes --prompt "Review the changes and add inline comments"

# Run with a completion promise for scripting
autohand --completion-promise --prompt "Generate API documentation"

Automatic skill detection

Enable automatic skill detection to let the agent use skills without explicit invocation:

# Enable automatic skill detection
autohand --auto-skill

# The agent will automatically detect and use relevant skills
# based on the task context

Export and share sessions

# Export current session
/export

# Share session with team
/share

Multi-agent patterns

For complex tasks, multiple agents working in parallel can be more effective than a single agent.

Parallel exploration

Run multiple agents to explore different solutions:

# Terminal 1: Agent exploring solution A
autohand --prompt "Implement caching using Redis"

# Terminal 2: Agent exploring solution B
autohand --prompt "Implement caching using in-memory LRU"

# Compare results and choose the best approach

Specialization

Different agents for different tasks:

• Research agent: Explores codebase, gathers context
• Implementation agent: Writes code based on research
• Review agent: Checks implementation for issues
• Test agent: Writes and runs tests

External agents

Manage external agent integrations:

# List configured agents
/agents

# Create a new agent configuration
/agents-new

# External agents can be configured for specialized capabilities
# like browser automation, data analysis, or domain-specific tasks

Permission management

Autohand uses a permission system to control what actions agents can take.

View and manage permissions

# View current permissions
/permissions

# Permissions control access to:
# - File system operations
# - Command execution
# - Network requests
# - Sensitive operations

Permission levels

• Ask: Prompt before each action
• Allow: Permit automatically
• Deny: Block automatically

Security considerations

Agents have significant access to your system. Follow these practices to stay secure.

Review sensitive operations

Always review agent actions that involve:

• Authentication and authorization code
• Database queries with user input
• API endpoints handling sensitive data
• Infrastructure configuration
• Dependency changes

Use sandboxed environments

For risky operations, use sandboxed or staging environments:

# Run agents against staging
DATABASE_URL=$STAGING_DB autohand --prompt "Migrate the database schema"

# Use auto-mode with git worktree isolation
autohand --auto-mode  # Changes happen in isolated worktree

Memory management

Use memory commands to manage what the agent remembers:

# View and manage agent memory
/memory

# Memory stores context between sessions
# Review periodically for sensitive information

Learning your codebase

Use agents to understand unfamiliar code. They're excellent at exploration and explanation.

Ask questions like a teammate

"How does the payment processing work in this codebase?"

"What happens when a user submits an order?"

"Where is authentication handled and what middleware is involved?"

"What's the data flow from API request to database?"

Generate documentation

# Document a module
"Create documentation for the order processing module, including:
- High-level architecture
- Key functions and their purposes
- Data models
- Common use cases"

Trace execution paths

"Trace the code path when a user clicks 'Submit Order'.
Show me every function that gets called and what it does."

When things go wrong

Agents aren't perfect. Here's how to handle common issues.

Agent is stuck in a loop

# Interrupt with Ctrl+C
# Then provide more context
"Stop. The approach isn't working because [reason].
Let's try a different approach: [alternative]"

Agent made incorrect changes

# Undo the last change
/undo

# Or revert with git
git checkout -- .

# Provide clarification
"That's not what I meant. I need X, not Y."

Agent doesn't understand the codebase

# Initialize an AGENTS.md file
/init

# Or provide more context manually
"Before making changes, read these files to understand the architecture:
- lib/core/engine.ts
- lib/core/types.ts
- docs/ARCHITECTURE.md"

Switch models for better results

# Switch to a different model during session
/model z-ai/glm-4.7

# Or start with a specific model
autohand --model gpt-4o

# List available models for your provider
/model

Get help

# View all available commands
/help

# Send feedback about issues
/feedback

Summary

Working effectively with AI code agents comes down to a few key principles:

1. Plan first: Ask for plans before complex implementations
2. Manage context: Use AGENTS.md, /init, skills, and /new for fresh starts
3. Be specific: Clear prompts with acceptance criteria
4. Test everything: Tests are your safety net
5. Review actively: Watch progress, use /undo, and interrupt early
6. Automate workflows: Use --auto-mode and --auto-skill for repetitive tasks
7. Stay secure: Manage permissions and review sensitive changes carefully

The more you work with agents, the better you'll get at communicating with them. Start with small tasks, build confidence, and gradually take on more complex challenges.