# Tips for AI coding agents

I’ve been using AI coding agents for a while, and I’d like to share my findings. The findings are mainly about Claude Code, but may apply to all coding agents, like opencode, if there’s no note about it.  

---

### Intuitive API is a must.

Everything should work intuitively, based on the **name**. AI tends to avoid digging into the lower layer unless you explicitly instruct it to fix it. For example, if `enabled: false` does not work in the code below, AI will fail to fix it most of the time because it *assumes* that the option works as expected.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1767580108213/41e090a1-8546-4311-abec-666c94f6c4e3.png align="center")

### Subagents may reduce context window usage.

> Use subagents proactively.

You can utilize subagents to reduce the usage of the **main** context window. The only thing you need to do is saying `Use subagents proactively` in the prompt. It’s useful when you need to do a very large task. It makes Claude Code less intelligent for tasks that require the organic analysis of multiple clues, though.

Note: I didn’t define any subagents in my repository. General subagents are enough for this trick.

### The API reference document reduces the guess-and-grep loop.

If you don’t specify the name of the method you want to fix, the AI agent will guess the method/variable/module name and grep for it **repeatedly** until it finds the relevant code.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1767582431474/95ec0a3e-f479-486b-bbbf-605cf491f911.png align="center")

This means that if you can provide an API reference document listing all method names, the coding agent will be much more efficient. As a side note, the best thing is an RPC API specification file that lists all method names and only the RPC message name.

```plaintext
syntax = "proto3";
package delino.appcore.v1;
option go_package = "github.com/delinoio/cloud/rpc/appcore";

import "appcore/auth.proto";

service AppCore {
  rpc UpdateUserProfile(UpdateUserProfileRequest) returns (UpdateUserProfileResponse);
}
```

Mentioning this file would give the AI agent

* the name of RPC methods to grep for
    
* the names of RPC message types to grep for
    

so the AI agent will never need to repeatedly guess the names.

### Provide the design document, and ask the AI agent to update it.

The source of truth **was** the code. And yeah, the primary source of truth is still code. But you can’t feed the whole code into AI agents, and updating code requires lots of tokens. I’m not talking about the token cost. It’s about the context window size. That’s why we need a specification document that is **up-to-date with the codebase** and **committed to the repository**.

Luckily, having one is easy. You don’t need to update it manually. Instead, instruct the AI agent to read the design document before any task, and update it as required.

### You may start building in a separate session after creating a plan.

* Applies to: Claude Code.
    

The plan mode is great. It’s a really wonderful feature that allows you to create a comprehensive task input prompt that mentions all the relevant files. But sometimes, Claude Code runs compaction nearly immediately after approving the plan because it does not clear the context before executing the plan. If you want, you can instruct it to write the comprehensive task prompt as a Markdown file, and `/clear` the context window, and paste it there.

In this way, Claude Code will run with a fresh context window, reading referenced files as required. It’s useful if you've done a lot of ping-pong with the planning agent.

### Provide project structure.

You can provide the project structure using the instruction file (`CLAUDE.md`/`AGENTS.md`) or a custom command. Giving the project structure also reduces the number of tokens wasted to guess the project structure.

Personally, I prefer a monorepo, so I have commands like `/work-on-devbird` that mentions the relevant frontend/backend directory, the RPC definition, and the design documents.

### Mention the filepath or the names of utility functions.

This is a good fit for the instruction files, like `CLAUDE.md` and `AGENTS.md`. The AI agent has limited knowledge of the project, so it may repeat the same code over and over. It isn’t good. If you instruct it to read the utility file beforehand, it will reuse the existing function.

### If you don’t understand something, throw the whole text to the Plan Mode.

You don’t need to understand everything, seriously. You don’t need to give it a perfect prompt. Instead, you can use plan mode to expand your thoughts within the project context. Sometimes I didn’t understand some requirements because they are specific to the project, but Claude Code's plan mode expanded them into a concrete plan prompt. You can even ask Claude Code to ask you back. You can do clarification based on the questions the Claude Code asks.