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.
• Name your elements, otherwise there can be modifications in unexpected places.
• Sometimes an implementation becomes stuck in loop, don't fear to delete the entire feature history and start again implementing it with a better instruction, sometimes its even the only way to make it work correctly.
• When you are unable to do something, ask why. It will explain you why the code is structured in a way that cannot be changed as how you want, then you can rephrase your request on how it should be redesigned.

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.

Advanced Techniques

Extracting valid features from semi-failed experiments

When you are making large changes and, despite many attempts, you can't get the code to work perfectly, you might find yourself in a "loop" where new iterations fix one thing but break previous functionalities. This often leaves the codebase in an unusable state with unknown side effects.

Instead of pushing forward blindly, follow this recovery pattern:

1. Create a temporary history: Commit your various attempts (even the broken ones) into a temporary branch or a series of local commits.
2. Generate a global diff: Create a single diff or patch of all the changes happened, not as a final one but as an "all of them".
3. Reset to a clean state: Revert your working directory to the last known stable point.
4. Targeted implementation: Provide the AI with the global diff as context and ask it to: Based on these differences, implement EXCLUSIVELY the following specific feature/logic.

git log -p origin/main..main > global-patch.diff

This approach allows the AI to act as a filter, extracting only the useful logic fragments that actually worked during your experimentation while ignoring the "noise" and bugs introduced during the failed iterations. You can then rebuild your feature step-by-step, ensuring each piece is solid before moving to the next.

Using Reference Diffs for API Porting

When porting a complex system (like a filesystem) to a newer environment with a different API (e.g., a newer Linux Kernel), you can use a "reference implementation" to guide the AI.

For example, to port the ReiserFS (v3) filesystem which was deprecated around kernel 6.x into a new kernel version:

1. Identify a reference: Choose a similar, well-maintained component (ideally smaller) in the target environment (e.g., the fs/ext4 directory in the kernel) and start from a version on which the previous code of target (reiserfs) was fully working.
2. Generate a reference diff: Create a diff of that reference component between the old and new versions. This patch acts as a "visualizer" of the API changes.
3. Analyze the patterns: In this diff, you might see systematic changes, such as functions or variables previously named page being renamed to folio.
4. Guided Adaptation: Provide this reference patch to the AI and ask it to edit your own files (e.g., ReiserFS source files) to adapt them to the new API, using the reference patch as inspiration for the required transformations.

This technique provides the AI with concrete examples of how the environment has evolved, making it much more accurate at applying those same patterns to your specific codebase.

Examples:

git diff v6.10...HEAD -- fs/ext4/ > patch.diff   # this diff is too long for AI, so let's make it shorter:

git diff -U0 --minimal --no-renames --no-prefix v6.10...HEAD -- fs/ext4/  # that's much better, let's make it even more smaller, to not consume so many tokens:

Large Complex Features

When requesting a large and complex feature, AI sometimes struggles to keep all factors in mind for a correct implementation. To handle this effectively, follow this iterative refinement process:

1. Define the Goal: Start by defining exactly what you want to achieve with as much detail as possible, ensuring no requirements are missed. Save these full instructions in a temporary text file.
2. Initial Generation: Launch the request. If the feature is very large, you might need to run the implementation prompt multiple times or in stages.
3. Create a Progress Diff: Generate a diff (patch) that shows the combined changes from the stable starting point to the current state.
4. The Feedback Loop: Provide the AI with this patch.diff and the original full instructions. Ask it to analyze if the current implementation meets all requirements and is free of bugs.
5. Deep Thinking: It is crucial to use "think" or "deep-thinking" modes (or use "ask" instead of "implement") during this stage. This forces the AI to analyze the existing code against the requirements before it attempts to apply fixes.
6. Iterate: Repeat this process in several loops: generate a new patch.diff, provide the original instructions again, and ask for a gap analysis and final implementation. This ensures the AI doesn't "forget" details from the initial prompt as the conversation grows.

Example commands to facilitate this:

# Generate a patch of everything done so far
git diff 2d596583...HEAD > patch.diff

# Feed the patch back to the AI for analysis against original instructions
aider --auto-commits --architect --read patch.diff source1.py source2.py