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.
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.
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.
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
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.
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.