Getting the Most Out of IronCode: Patterns That Actually Work

IronCode is an autonomous agent, which means it can do a lot with a vague prompt — and produce the wrong thing confidently. The difference between a tool that saves you an hour and one that creates cleanup work is mostly in how you use it.

These are the patterns that work.

Give it a definition of done

The most common mistake is a prompt that describes the work without describing success:

# Vague — IronCode has to guess when it's done
> Improve the error handling in the auth module

# Specific — IronCode knows exactly when to stop
> Add error handling to every function in lib/auth.ts that currently has none.
> All errors should use the AppError class from lib/errors.ts.
> Run the tests when done. If they fail, fix them before stopping.

The second prompt gives IronCode a checklist. It reads the files, identifies functions without try/catch, adds error handling, runs tests, and stops when tests are green. The first prompt leaves it guessing what "improve" means.

Reference your existing patterns explicitly

IronCode reads your codebase, but it doesn't always pick the right reference files. Help it:

> Add a new endpoint POST /api/tasks that creates a task.
> Follow the same pattern as /api/projects — validation, error handling, tests.

When you name a specific file or route as the reference, IronCode reads it first and uses it as a template. The output will match your existing style instead of defaulting to whatever pattern the AI has seen most in its training data.

Use skills for structured work

The built-in skills encode workflows that most developers would agree are good practice but often skip under time pressure.

/tdd — when you care about test coverage

> /tdd Add a rate limiter to the authentication endpoints

IronCode will write a failing test first, then write the minimum code to make it pass, then refactor. It won't write the implementation and then retrofit tests around it. If you want the red-green-refactor discipline without having to enforce it yourself, use /tdd.

/debug — when you have a bug but not the root cause

> /debug Users are getting logged out after exactly 24 hours even though
> the session should be 30 days. The logs show no errors.

The /debug skill forces IronCode to investigate before it proposes fixes. It reads relevant code, checks the logic, forms a hypothesis, and only then makes a change. This prevents the pattern of "try this fix, try that fix" that wastes time.

/qa — before you ship

> /qa http://localhost:3000

Runs a headless browser against your app, systematically tests every page, documents every bug with screenshots. Useful as a final check before opening a PR or deploying.

Be specific about scope

IronCode respects explicit scope boundaries. If you're worried about it touching things it shouldn't:

> Refactor the UserService class to use dependency injection.
> Only modify files in src/services/ and src/services/__tests__/.
> Do not change any route handlers or controllers.

The scope constraint isn't just defensive — it also produces better results because IronCode knows exactly what's in bounds and can reason about the changes more precisely.

Ask it to explain before changing

For unfamiliar codebases or risky changes, ask for a plan first:

> Read the payment processing flow and explain how it works.
> Don't make any changes yet — I want to understand it before we modify anything.

Then, once you've confirmed IronCode's understanding is correct:

> Good. Now add idempotency keys to the charge creation call.

This two-step pattern is especially useful for onboarding to a new codebase or making changes in areas you don't fully understand yet.

When to use IronCode vs when not to

Good fit:

• Cross-cutting changes ("add this to all 20 endpoints")
• Adding a feature to an existing, well-structured codebase
• Writing tests for code that exists but isn't tested
• Applying a consistent refactor across multiple files

Not a good fit:

• Exploring a problem space where you don't know what you want yet — use a chatbot for this
• Writing highly novel algorithms — IronCode is better at applying known patterns than inventing new ones
• Tasks where the output requires subjective judgment you haven't encoded in the prompt

The more precisely you can describe what "done" looks like, the better IronCode performs. Tasks with fuzzy success criteria produce fuzzy results.

Installation and setup

# Install globally
npm install -g ironcode-ai

# Start
ironcode

# Or run a one-shot task without the interactive UI
ironcode run "Add TypeScript strict mode and fix all resulting errors"

Configuration lives in .ironcode/ironcode.jsonc in your project root. The main things to set are your AI provider and model:

{
  "model": "claude-sonnet-4-5",
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  }
}

The full configuration reference is in the docs.