Effective Agent Instruction

#programming #ai #vibecoding #githubcopilot

You would think AI coding is simply providing the coding agent with your instructions, then sit back and enjoy the work AI has accomplished. But imagine you return to find a thousand comments that have completely ruined your codebase, and far from your original intention.

To avoid this unfortunate common pitfall, the key is to master the art of instructing AI, which means to let the AI agent fully understand your intention. Plus, you also need to make sure your idea/design is flawless.

My approach is a combination of prompt engineering and a workflow. Here is my approach.

1. Defiine Command Alias

I have the following as the custom prompt to the coding agent:

## Command Keywords
- **!!**: Create requirements → focus on `what`, not `how`, no plan → save to `docs/requirements/req-{name}.md` → wait for confirmation;
- **AA**: Create a detailed functional implementation plan (no optimization) as check list → save the list to `docs/plan/plan-{name}.md` → wait for confirmation;
- **AP**: Review requirements → think hard ensure no flaw → provide suggestions → wait for confirmation;
- **AS**: Execute plan → implement step-by-step → mark done in plan → git stage changed and commit;
- **!!!**: Update the requirements, plan, and implement;
## Interaction Guidelines
- When you are done or need my input → play sound :`afplay /System/Library/Sounds/Glass.aiff`

I put it in CLAUDE.md for Claude Code; copilot-instructions.md to GitHub Copilot. And ready to start working with them.

2. Workflow

I usually following the steps below:

I describe ideas and !! to create a requirement document.
AP, AP, AP … to review and confirm the requirements
AA to create an implementation plan - I also review the steps careful before letting the agent to code
AS to implement
If I change my mind, I will describe the ideas and !!! to update the requirement doc and plan doc

After all, this approach will ensure the source code to have better chance to meet our requirements.

We will also have good the requirement and execution result documentation.The documents are extremely important. We can use for analysis, verification and even reimplement in the future. They are the true source code.

BTW, you may have noticed a bonus alias to play a sound once the agent finished a task or waiting for confirmation. A handy reminder.

3. One More Thing

The approach above applies to all coding agents. It does not require the code agents to provide facilitates on things like design mode, ask mode, act mode, and etc. Just use plain old prompts, the LLM is smart enough to understand the command alias to execute the workflow including when to start to code.

It worked very well for me in the GitHub Copilot Agent Mode with Claude Sonnet 3/4. Not so well with GPT and Gemini though.