Skip to content

Basic workflow with AI coding tools#

This document suggests basic workflows to use AI coding tools and how to get the best out of them.

Always follow your team's processes

Each engineering teams has its own processes (peer reviews, groomings, maximum PR size, code coverage thresholds, etc.). AI usage must always respect those processes: AI coding tools help you be more efficient at each step of the process, but remain subject to the processes so that AI generated code still pass our quality guidelines.

Plan Mode#

Most AI coding tools have a "plan mode". We observe much better results when starting working on a topic with this mode: it provides better control over what the AI will be doing and allows engineers to better scope and explain the problem while ensuring the approach is correct. When using this mode, the AI won't write any code but will rather focus on understanding the context by:

  • asking questions to the engineer
  • browsing the codebase

The goal of this phase is for the AI to build a plan to address the issue. To achieve this, it is key that the engineer provides the right context. The AI must be fed with information from the JIRA / GitHub ticket (functional behavior) and knowledge of the engineer about the app (technical context). Even if the app is well documented, providing entry points to the AI will greatly help. Here are some examples of what to specify at this stage:

  • Explanation of the issue and expected behavior (typically, the GitHub or JIRA ticket),
  • Context about the involved mechanisms of the app with quick references to the documentation or to the codebase,
  • Possible approaches you already have in mind and encourage the AI to be critical about your proposed approaches, asking it to evaluate pros & cons and maybe suggest other state-of-the-art approaches,
  • Expected outcomes on top of the implemented code, such as documentation if needed, unit/integration tests, specific scenarios to cover with tests, etc.

Always follow your team's processes

Think of it as if you were asking a good engineer to work on this task, but they never worked on it before!

At the end of this phase, the AI will provide a plan, summarizing the problem, the proposed approach and the considered trade-offs. It is key that the engineer reviews this plan thoroughly, understands it well and agrees with it. Otherwise, you can iterate in Plan mode and ask for modifications by explaining why the proposed plan is not good enough. If the plan is well-defined, the quality and speed of the next phases is greatly increased.

Implementation mode#

Once the plan is accepted, you can start using the "implementation mode" of the coding tool. The agent will execute the plan and implement the needed changes. Two main approaches are suggested, depending on how mature and secure the codebase is, and your confidence level in the plan. For clear plan in safe codebases (good test coverage, runs locally, etc.), you can give more autonomy to the coding tool and let it iterate itself between implementation and testing, and only get involved at later stages when the task is completed. For more uncertain tasks, you can take a much more controlled approach with very frequent checkpoints.

Autonomous agent iterations for safe plans#

This approach allows you to be less involved during the development by the AI. As a result, you will get a larger implementation to review and test at once, at the end which is more error-prone ; the cost of fixing things afterwards will be higher. This approach is recommended if the codebase is mature enough (documentation, testing running locally) so that the agent can iterate with testing itself. The goal of this approach is that the AI implements the plan, including automated tests, and then run itself automated and even "manual" tests (testing scenarios through API calls for instance). To rely on this approach, the codebase must be running locally (typically on docker) and have a good automated test setup.

To use this approach, you must prompt the AI by asking it to implement the plan from plan mode, implement the test coverage, run the automated test and manual tests and iterate until they all pass. Specify to the AI how to access the local instance and run the tests: is it running on docker? Does it need to use the venv? Etc.

You can encourage the AI to test itself the changes through automated and "manual" tests, and to investigate potential issues by adding temporary logs to understand the behaviors. Those are technics that have proven to provide good results.

This AI will enter a long-running iterative loop and exit once all the tests are passed, or if it faces a very complex issue which usually means the plan needs to be reworked.

Short human/AI feedback loop on small chunks of code#

This approach is better suited in uncertain plans and codebases. It requires much closer attention from the engineer as the AI will write small chunks of code and ask for validation from the human before continuing. In this approach, the AI is mostly used as a way to speed up writing code, but the process itself remains controlled by the human.

To use this approach, you must prompt the AI by asking it to implement the plan from the plan mode through small iteration of up to 100 lines of code. Prompt the AI that, once a chunk of about 100 lines of code has been written, the AI must pause and provide the human with a very quick explanation of what was written, so the engineer can review and validate. Once validated, the AI can go to the next iteration.

This approach allows spotting early on if the AI is taken a wrong approach or making mistakes. The cost of fixing issues is much lower.

Review#

Once the implementation is completed (the expected behavior is validated, tests are passing, etc.), the code must be reviewed. AI coding tools can help to perform a first review. You can spin up a new conversation with the AI coding tool and ask to perform a code review of the pull/merge request. This ensures that a new instance of the AI performs the review, hence coming without the context about the plan and implementation, just as if a peer was reviewing the PR/MR. If your codebase has guidelines for reviews and code style, mention them to the AI, so they are used.

AI reviews usually pinpoint suggestions or issues compares to the state-of-the-art approaches. While they can be very relevant, the engineer should always consider whether this makes sense in the context of the app or if it is over-engineering.

AI reviews allow to have a first quick "pseudo peer" review so a first iteration of review/fixes is possible for the engineer. It makes following reviews easier and faster. A real human peer review is still needed if this is part of your team's process.

In any case, a thorough review of the code by the engineer working on the PR/MR is needed before sending it to another engineer for a real peer review: the engineer working on the PR/MR remains responsible for the code submitted, even if AI was used in the process.