---
title: "Instructing Autohand Code"
source: https://docs.autohand.ai/guides/beginners/instructing-autohand
---

# Instructing Autohand Code

The quality of your instructions determines the quality of the results. Learn how to communicate with Autohand Code to get exactly what you need.

## How Autohand Code understands you

When you give Autohand Code an instruction, it does not just read the words you typed. It reads your entire codebase first, including your project structure, dependencies, configuration files, and existing patterns. This means Autohand Code already has context about your project before it writes a single line of code.

Here is what happens when you send a message:

1.  Autohand Code scans your project files and understands the overall architecture
2.  It identifies relevant files, imports, and patterns that relate to your request
3.  It builds a plan for how to accomplish what you asked
4.  It shows you the plan and waits for your approval before making changes

This planning step is key. You always have a chance to review what Autohand Code intends to do before it does it.

**Tip:** Use Plan Mode (Shift+Tab or --plan) to see what Autohand Code will do before it does it. This is especially useful for large or unfamiliar codebases.

## Be specific about what you want

The more precise your instruction, the better the result. Instead of vague requests, include the file or component name, describe the expected behavior, and mention any constraints like the framework or patterns you want followed.

Compare these two approaches:

``` bash
# Vague - Autohand Code has to guess what you mean
autohand "fix the form"

# Specific and clear - Autohand Code knows exactly what to do
autohand "Add input validation to the signup form in src/components/SignupForm.vue - email must be valid, password at least 8 characters"
```

When you describe the expected behavior, Autohand Code can also write better tests and handle edge cases:

``` bash
# Context about expected behavior
autohand "The /api/users endpoint returns 500 when the email field is missing. Add proper validation that returns 400 with a descriptive error message"
```

## Use context references

Autohand Code supports several ways to point it at specific files and context. This saves time and removes ambiguity about which parts of the codebase you are talking about.

### Reference files with @

Use the @ symbol to mention specific files directly in your prompt. Autohand Code will focus on those files first:

``` bash
# Reference files directly
autohand "@src/models/User.ts @src/api/users.ts add a phone number field with validation"
```

### Pipe input for extra context

You can pipe output from other commands into Autohand Code. This is useful when you want Autohand Code to analyze logs, diffs, or any other text:

``` bash
# Pipe a git diff for review
git diff | autohand "explain these changes"

# Pipe error logs for diagnosis
cat error.log | autohand "diagnose this error and suggest a fix"
```

### Include error messages

When debugging, paste the actual error message into your prompt. Autohand Code can trace the error back through your codebase and find the root cause much faster than if you just describe the problem in your own words.

## Use the right mode for the task

Autohand Code has several modes, each suited to different types of work. Picking the right one makes a real difference in how smoothly things go.

### Interactive mode

Best for exploration and back-and-forth conversation. Use this when you are not sure exactly what you need yet, or when you want to iterate on a solution.

### Plan mode

Best for understanding before executing. Autohand Code shows you a detailed plan of what it will change and why, and waits for your approval. Great for working in unfamiliar code.

### Auto mode

Best for well-defined, multi-step tasks. Autohand Code will plan, execute, test, and fix without stopping for approval at each step. Use this when you are confident about what you want.

### Pipe mode

Best for scripting and CI/CD pipelines. Autohand Code reads from stdin and writes to stdout, so you can chain it with other command-line tools.

## Break complex tasks into steps

For larger features, breaking the work into smaller pieces leads to better results. Autohand Code handles focused, single-purpose instructions more reliably than broad, multi-part requests.

A good pattern is to work from the data layer up to the UI:

``` bash
# Step 1: Data model
autohand "Create a Task model with title, description, status, and due_date fields"

# Step 2: API endpoints
autohand "Add CRUD endpoints for the Task model with proper error handling"

# Step 3: Frontend
autohand "Create a task list component that calls the Task API endpoints"
```

Each step builds on the previous one. Autohand Code will see the code from the earlier steps and use it as context for the next one.

You can also use Plan Mode to explore first. Ask Autohand Code to outline the approach, review the plan, and then switch to execution once you are happy with the direction.

## Use AGENTS.md for project context

An AGENTS.md file in your project root gives Autohand Code persistent context about your project. It reads this file automatically at the start of every session, so you do not have to repeat the same background information every time.

A good AGENTS.md includes:

-   Your tech stack and key dependencies
-   Coding conventions and patterns your team follows
-   Important commands for building, testing, and running the project
-   Any project-specific rules or constraints

For a full walkthrough on writing effective AGENTS.md files, see the [AGENTS.md guide](/docs/working-with-autohand-code/agents-md.html).

## Let Autohand Code review before committing

Before you commit changes, use dry run mode to preview what Autohand Code would do without actually modifying any files. This is a safe way to check the approach before letting it run for real.

``` bash
# Preview changes without modifying files
autohand --dry-run "refactor the auth module"
```

You can also ask Autohand Code to review your own changes before you commit them:

``` bash
# Review your staged changes
git diff --staged | autohand "review these changes for bugs or improvements"
```

## Next steps

-   [Good vs. bad instructions](/docs/guides/beginners/good-vs-bad.html) - See side-by-side examples of what works and what does not
-   [SDLC integration](/docs/guides/beginners/sdlc-integration.html) - Use Autohand Code across your full development workflow
-   [AGENTS.md guide](/docs/working-with-autohand-code/agents-md.html) - Write effective project context files