DEV Community

Cover image for Effective Agent Instruction
yysun
yysun

Posted on • Edited on

Effective Agent Instruction

#programming #ai #vibecoding #githubcopilot

Introduction

You would think AI coding is simply tell the coding agent what you want, and then you can sit back and enjoy the work AI has accomplished. Wrong! Often you return to find a thousand commits that have completely ruined your codebase, and far from your original intention.

This is the reality of AI coding. The coding agent does not understand your requirements unless you provide them clearly. The agent will follow your instructions to the letter, but if those instructions are vague or incorrect, the results will be far from what you expected.

In this article, I will share my experience of using AI coding agents like GitHub Copilot create a Statement of Work (SOW) between you and the coding agent. This SOW approach will ensure that the agent delivers what you want, rather than what it thinks you want.

Here is the workflow I have been using to create a SOW with AI coding agents.

  1. Define the Requirements: I describe my requirements. No need to be robust. I let AI create the document for me with prompts like:"focus on what, not how, not optimization". Once I have the requirement doc, I will ask AI to verify it: "Review requirements → think hard ensure no flaw → provide suggestions → wait for confirmation."

  2. Implementation Plan: Once both AI and I are happy with the requirement doc, I will ask AI to create an implementation: "Create a implementation plan → save to docs/plan/plan-{name}.md → wait for confirmation."

  3. Tests and Acceptance Criteria: A good new is that AI usually creates the test scenrios and acceptance criteria automatically. I do a final review and approve AI to proceed with the implementation.

You can see are many repeaititive steps in the process of typing same prompts again and again. To make it easier, I have created a set of command aliasin in CLAUDE.md for Claude Code. Or in copilot-ininstructions.md for GitHub Copilot.

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;
Enter fullscreen mode Exit fullscreen mode

2. Workflow

I usually following the steps below:

  • I describe ideas and !! to create a requirement document.

\!\!Create Requirements

  • When requirements are ready, I use a lot AP, AP, AP … to review and confirm the requirements.

AP - Review Requirements

  • Then, I use AA to create an implementation plan. AI analyzes the current code base and identifies what needs to be change.

AS - Create Implementation Plan

  • Do not rush to implement yet. Use AP again and again to ensure the plan is right. You will be supprized.

AP - Review Implementation Plan

Clarify Questions

  • Only when we are cool with plan, I will use AS to let AI start implementation.

AS - Implement the Plan

  • Now, AI takes over and write code step by step.

AI Execution

  • If I changed my mind, I can always use !!! to update the requirements, plan, and implementation. AI will re-evaluate the plan and code accordingly.

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.

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.

4. Conclusion

The coding paradigm is shifting, from vibe coding to effective agent instruction. By creating a SOW between you and the coding agent, you can ensure the agent will deliver what you want. By using the command alias, you can speed up the process and concentrate on the requirements and implementation plan, rather than the typing prompts again and again.

BTW, Here is Github repository that contains the command alias collage-cli

Happy coding with AI!

Top comments (0)