A Practical Guide to Avoiding Overengineering, Unnecessary Code Changes, and Development Mistakes

AI coding agents are changing the way developers build software. Tasks that once required hours of writing and debugging code can now be completed much faster with tools such as Google Antigravity. From fixing bugs and building features to understanding existing codebases, AI can make software development more productive.

But there is a catch.

An AI agent can write code quickly and still make the wrong decisions. It might rewrite a working component to fix a small bug, introduce an unnecessary dependency, change files unrelated to the task, or claim that everything works without running the appropriate tests.

If you have worked with AI coding tools for a while, you may have experienced something similar: you ask for one small change, and suddenly several other parts of the project look different.

The problem is not always the code itself. Sometimes, the agent simply lacks clear instructions about how it should work.

That is why I created a reusable project instruction template for Google Antigravity. It helps establish practical rules for understanding a project before editing it, keeping changes focused, protecting existing work, testing the implementation, and reporting the actual results.

You can find the complete instruction file on GitHub:

Get the Google Antigravity Project Instructions on GitHub

In this guide, we will explore why these instructions matter, how to use them, and how they can improve your everyday AI-assisted development workflow.

Why Does an AI Coding Agent Need Project Instructions?

Imagine asking an AI agent to fix a validation issue in a registration form.

Instead of inspecting the existing validation logic and correcting the problem, it introduces a new validation library, rewrites the form component, and changes several unrelated files.

The original problem may be fixed, but now you have more code to review, more potential compatibility issues, and a larger set of changes to test.

This is a common example of overengineering: solving a small problem with a solution that is more complicated than necessary.

Other problems can occur when an AI agent does not understand the project’s boundaries. It may duplicate functionality that already exists, modify configuration unnecessarily, overlook existing tests, or make assumptions about how the application is supposed to work.

Clear project instructions help address these problems by establishing expectations before the agent begins implementation.

The goal is not to restrict AI from writing useful code. It is to help the agent make decisions that are appropriate for the project and the task at hand.

Three Ways to Guide Google Antigravity

A practical approach is to combine permanent project instructions with prompts written for individual tasks.

1. Use a detailed prompt for complex tasks

Some tasks require more planning than others.

Starting a new project, changing the architecture, migrating a database, modifying authentication, or refactoring a critical module can involve decisions that affect many parts of an application.

For these situations, use a comprehensive prompt that explains the expected outcome and establishes clear boundaries.

Ask the agent to:

• Confirm that it is working in the correct repository.
• Inspect the relevant source code, documentation, configuration, and tests.
• Understand the current architecture before proposing changes.
• Identify the smallest reasonable implementation.
• Avoid unrelated refactoring and unnecessary dependencies.
• Protect existing changes and important data.
• Verify the implementation with appropriate tests.
• Review the final changes before reporting completion.

A detailed prompt is particularly useful when mistakes could cause significant rework or introduce security, compatibility, or data-integrity problems.

2. Use a short prompt for everyday development

Routine tasks do not always need lengthy instructions.

For example, fixing a small bug, adjusting a button, updating a query, or adding a minor feature can usually be handled with a concise task prompt, provided the agent already has access to the project’s rules.

Here is a reusable example:

Implement only the requested change. First inspect the relevant existing code and follow the project’s established conventions. Make the smallest appropriate modification, reuse existing functionality, and avoid unrelated refactoring or unnecessary dependencies. Preserve existing work and data. Run the relevant checks, review the final diff, and report what changed, what was tested, and any remaining limitations. Do not deploy, publish, or perform destructive operations unless explicitly authorized.

Simply replace the task description with your actual requirement.

The benefit is straightforward: you spend less time repeating general instructions and more time explaining what you want to build.

3. Keep permanent instructions in the project

The third approach is to maintain a Markdown file named:

ANTIGRAVITY_PROJECT_INSTRUCTIONS.md

This file acts as a reusable reference for how an AI coding agent should work within a project.

Instead of repeating the same rules every time you start a task, you can maintain them in one place and direct your development workflow to read and follow them.

I have prepared a reusable version that you can view here:

ANTIGRAVITY_PROJECT_INSTRUCTIONS.md — View on GitHub

The template covers project boundaries, code inspection, scope control, overengineering, dependency management, Git safety, security, testing, documentation, and final reporting.

It is intended to be adapted to your own project rather than treated as a universal set of rules that fits every development environment.

What Does the Instruction File Actually Do?

The value of the file comes from the working habits it encourages. Here are some of the most important areas it addresses.

1. Understand the project before editing

Before making changes, an agent should inspect the relevant files and understand how the existing implementation works.

This includes reading applicable documentation, reviewing configuration, examining related components, and checking the tests.

Why does this matter?

Because a project may already have a utility, service, or framework feature that solves the problem. Without inspecting the existing implementation, the agent may create a second solution unnecessarily.

For example, if an application already has a central service for sending email notifications, a new feature should normally reuse that service instead of introducing another independent email system.

The principle is simple: understand what already exists before deciding what needs to change.

2. Keep the task within its original scope

If you ask for a bug fix, the agent should focus on that bug.

It should not automatically redesign the interface, rename unrelated files, add bonus features, or start the next development phase.

Sometimes, investigation reveals another issue that deserves attention. The agent can report that issue and explain why it matters. It should not silently expand the task unless the additional work is necessary or authorized.

This makes development more predictable and helps you review changes with confidence.

3. Avoid unnecessary complexity

More code does not automatically mean better code.

A small feature may not require a new service layer. A straightforward operation may not need a queue. A simple configuration option may not justify building an entirely new configuration framework.

The instruction template encourages the agent to prefer the simplest solution that satisfies the actual requirements.

That means reusing suitable framework capabilities, following existing project conventions, and introducing abstractions only when they solve a real problem.

The goal is not to avoid good architecture. It is to avoid complexity that has no clear purpose.

4. Make focused, reviewable changes

When a task requires changing one function, rewriting the entire file is usually unnecessary.

Focused changes are easier to understand, test, and maintain. They also reduce the chance of accidentally breaking unrelated functionality.

The agent should inspect the affected files before editing, modify only the necessary sections, and review the resulting changes.

This is particularly important in established projects where existing code may contain custom logic that should not be disturbed.

5. Protect existing work

An AI agent should not assume that every uncommitted change is disposable.

A developer may have unfinished work in the repository that has not yet been committed. Automatically resetting, deleting, overwriting, or cleaning those changes can cause serious problems.

The template therefore emphasizes checking the working-tree state and preserving existing work.

If unexpected changes appear or a risky operation seems necessary, the agent should pause and ask for clarification instead of proceeding blindly.

6. Be careful with dependencies and Git

Installing a new package may seem like an easy solution, but dependencies add maintenance, compatibility, and security considerations.

Before adding one, the agent should check whether the project already has the required functionality or whether the framework can handle the task without additional packages.

Git operations also require care. Destructive resets, forced pushes, history rewriting, and automatic cleanup can affect work beyond the immediate task.

The agent should not automatically push code, merge branches, deploy an application, or publish a release simply because the implementation is complete.

Those decisions belong to the developer unless permission has been explicitly granted.

7. Respect security and data boundaries

Software development often involves sensitive information, user data, credentials, and production systems.

The agent should preserve existing security controls, validate untrusted input where appropriate, and avoid exposing secrets or confidential configuration.

It should also respect restrictions on external access. Downloads, external API calls, uploads, scraping, and production operations should not be performed without appropriate authorization.

Destructive production database operations, record deletion, and data overwrites require particular caution.

When the task unexpectedly requires access or permission that has not been granted, the agent should stop and explain what is needed.

8. Test the implementation instead of guessing

One of the most important rules is that an agent should not claim success without evidence.

Depending on the project, verification might include:

• Type checking or compilation.
• Focused unit tests.
• Integration and regression tests.
• A production build.
• Smoke tests.
• Visual inspection of affected interfaces.
• Security-related failure-case testing.

Not every task requires every check. The appropriate verification depends on what changed and how risky the change is.

If a test cannot be run because the necessary tooling is unavailable, the agent should report that limitation honestly.

It should never disable a failing test, bypass a feature, or hide an error simply to produce a successful-looking result.

9. Review the final changes

Before finishing, the agent should inspect the final diff and confirm that the modifications are relevant to the requested task.

For a Git-based project, these commands are useful:

git status --short
git diff --check
git diff

They help identify changed files, whitespace problems, and the actual modifications made during the task.

The agent should also check for unrelated edits, accidental configuration changes, exposed secrets, and incomplete implementation.

This final review helps catch problems that might otherwise go unnoticed.

10. Provide an honest completion report

A useful final report should tell you what happened, not simply announce that the task is complete.

It should summarize:

• The result of the task.
• The main changes implemented.
• The files affected.
• The tests and checks actually performed.
• Any outstanding issues or limitations.
• The final repository state, where relevant.

The task should be identified as passed, partially completed, failed, or blocked, as appropriate.

If the implementation is incomplete or a test could not be executed, that information should be made clear.

This makes it easier for a developer to decide whether the changes are ready for review, require further work, or need additional authorization.

How to Install the Instruction File in Your Project

Getting started is straightforward.

Step 1: Open the GitHub file

Visit the project instruction template:

View ANTIGRAVITY_PROJECT_INSTRUCTIONS.md

Step 2: Copy the file into your project

Place the file in the root directory of the project you want to work on.

For example:

my-project/
├── ANTIGRAVITY_PROJECT_INSTRUCTIONS.md
├── README.md
├── package.json
├── src/
├── tests/
└── docs/

This is only an example. Your project may use a different structure, language, or framework.

Step 3: Adapt the instructions

Review the template and adjust it to match your development environment, tools, framework, and team requirements.

For example, macOS and Homebrew guidance may be relevant to a Mac-based workflow but unnecessary for a Windows-only project.

Step 4: Make sure Antigravity reads it

Do not assume that the file will automatically be loaded merely because it exists in the repository.

Configure your Antigravity workflow to read and follow the instructions. The exact setup may depend on how you use the tool.

Step 5: Start each task with a clear requirement

Describe the feature or fix you want, explain any important constraints, and specify the expected outcome.

For everyday work, a short prompt may be sufficient. For major or high-risk changes, provide additional planning instructions.

Step 6: Review the result

Check the changes, inspect the test results, and confirm that the implementation matches your requirements before accepting or publishing it.

Remember that project instructions improve consistency, but they do not replace code review, testing, backups, or security checks.

A Practical Workflow for Everyday Development

You do not need to make every AI coding task complicated. A consistent routine is often enough.

1. Open the correct project and confirm its current state.
2. Make sure the project instructions are available to the agent.
3. Describe one specific task.
4. Let the agent inspect the relevant implementation before editing.
5. Review the proposed approach when the change is complex or risky.
6. Implement the smallest suitable change.
7. Run appropriate tests and validation.
8. Review the final diff and the completion report.
9. Decide whether any additional work should begin.

This workflow keeps the developer involved in the important decisions while allowing the AI to handle much of the implementation work.

Which Approach Should You Use?

Situation	Recommended approach
Starting a new project	Project instructions plus a detailed initial prompt
Major architectural changes	Project instructions plus a comprehensive task prompt
Database migrations	Project instructions plus explicit safety and verification requirements
Security-sensitive changes	Project instructions plus a detailed, risk-aware prompt
Routine bug fixes	Project instructions plus a short task prompt
Small interface changes	Project instructions plus a short task prompt
Adding a minor feature	Project instructions plus a task-specific prompt

The permanent file establishes the general working rules. The prompt describes what needs to be done now. Together, they provide a practical foundation for more consistent AI-assisted development.

Final Thoughts

AI coding agents can save developers time, but good results depend on more than the ability to generate code.

They need to understand the existing project, respect the requested scope, avoid unnecessary complexity, protect existing work, and verify their changes before reporting success.

A reusable project instruction file is a simple way to encourage those habits across multiple development tasks.

You can start with the template here:

Get the Google Antigravity Project Instructions on GitHub

Review it, adapt it to your project, and combine it with clear task-specific prompts.