Effective Software Orchestration with AI

This is a list of tips, suggestions, pitfalls, and best practices for using AI to help you write code.

• Never use cheap AI's, they will make you lose more time than they will save you
• Take your time to think, instead of fast typing your prompt, take your time to re-read your prompt to verify your instructions to external eyes who don't knows what you want.
• Use clever prompts, most of the times is clear in your mind but not clearly defined, AI cannot read your mind, only your text
• Always read the code generated by AI, sometimes it does things you don't want or has not understood correctly, sometimes it introduce bugs or removing features you wanted. But don't read the output AI given, read the commited diff, always have in another terminal the same directory where to run "git show" in order to see what did.
• When you have an important logic in your code that may not sound logic but is important to keep it, add a comment in the code explaining why is important, this will make AI to not remove it but also to understand correctly the behaviour wanted or needed.
• rewrite the git history when needed, use git rebase -i so you can move commits togheter or merge them.
• spend time to learn some programming concepts and principles, design patterns, etc... this will help you to know how to indicate to your IA exactly what must do, you are the brain and IA is the worker.
• Is the flow correctly working? ask the AI to: Write a comprehensive and complete behavioral analysis flow of the X-BEHAVIOUR, step by step actions and flow of it. The goal is to understand all its internal behavior to validate if they meet expectations.
• Label your source code features / elements with comments as you call them, so sometimes AI don't understand what you are refering to like "the button download" and you want it to not do mistakes.
• Don't ask for 2 changes unless you are describing a rewrite, IA's are like humans: cannot think in 2 things at the same time. Give it a single need per order.
• Leave instructions in the comments: sometimes AI is very stubborn removing your feature or things as you want them to be over and over, add a comment with the keyword "important" declaring how the next line/block should be and why is important to keep that way.

My 5-Step Coding Procedure

1. Implement
2. Verify
3. Fix
4. Rebase
5. Next

One topic at time

Unless they are small changes, don't do multiple topics in parallel, this is important for multiple reasons, first, you need your git history to be linear per topic, so you can:

• Easily rever the entire experiment if fails or you are not happy with the results, you can also remove it in the future if you don't need it anymore
• you can run a total diff of all the commit changes so you can see what exactly AI changed in the code, using something like git diff origin/main...main
• you can rebase all the commit into a single commit and having it like a single topic change, do this only if showing the full change like previously said looks clear and coherent.
• make sure to verify the entire functionality of the topic, if there's no bugs, etc... before to continue with the next topic

AI unable to solve an issue

Sometimes AI is simply unable to solve an issue (problem happens especially with issues), its commonly caused by something indirectly, or because the code structured in a confusing way, here more than even is needed your developer's knowledge.

When this happens you have a simple option:

• if the issue worked before, use "git bisect" to find the commit that introduced the issue, then you can try to fix it manually or ask AI to fix it showing the changes that introduced the problem

Or, you can ask the AI to refactor the entire topic, but this will require you to add very specific instructions on how it must work, for this, follow these steps:

• brainstorm yourself, as a programmer, what is the logic the application must follow, in order to correctly handle the case you need, for example:
  • at the init of the tool, verify if the conf file exists, if not, create a new one, if exists, verify that the configuration includes all the options we have in the application, and if not, add hte missing one with its default setting
  • when the setting modal appears, read first the user settings to use the values, so they can have changed if the user manually edited the file, when the settings are saved, re-write the entire file.
• write down the logic in a clear way, as if you were writing a specification for a junior developer
• ask AI to refactor the entire topic, providing the specification you wrote down

An extra TIP: ask AI to fill the code with many debug lines, so you can see where exactly it fails, a wrong flow, or a variable that is not what it should be, etc...

When something is hard to solve, don't be hurry and do another task while you leave a working process in trial & error until you solve the bug and rewrite the git history with the final change, remove older attempts if possible. Don't mix this step with other topics which can mix your history.