[{"content":"","date":null,"permalink":"/","section":"","summary":"","title":""},{"content":"Why This Post Exists #AI tools are great at writing code, but they’re terrible at picking up where you left off. You paste in part of a script, ask for help, and the model fumbles because it doesn’t know what it’s looking at.\nIt\u0026rsquo;s not necessarily a model problem — it’s a context problem.\nI started adding small hints to my projects to help the AI stay oriented: a few comments, a metadata file, a sentence or two at the top. The results were immediately better. Less wasted time. Smarter suggestions. Fewer “let me explain this again” moments.\nEventually, I realized this could be a pattern — one that’s simple, repeatable, and helpful across projects. In the future, it could even power IDE plugins and quality-oriented pipeline actions.\nWhat I Mean by AI-Maintainable Code #This isn’t about writing documentation for ChatGPT. It’s not about crafting prompts or retraining models. It’s just adding a layer of context that lives alongside your code — enough for an LLM to understand what’s happening without you having to spell it out every time.\nCall it metadata. Call it signposting. The point is: you’re making the code more legible to a machine that doesn’t know the backstory.\nThe Core Pattern (The AI-Meta Layer) #Here’s the basic structure I use:\nElement Purpose ai_context.yml/json Short, structured overview of the project: what it does, how it flows, where to start (yml preferred for token optimization) @ai: comments Inline notes about intent, not implementation README.ai.md (optional) A conversational explanation for the AI: purpose, pipeline, weird parts breadcrumbs.ai (optional) A lightweight changelog focused on “why” more than “what” These files are not just for the AI in the moment — they’re also friendly to embedding and vector search. If you’re using a retrieval-augmented (RAG) setup, you can index them to improve multi-file understanding and scoped responses.\nThis isn’t a heavy lift. Most files are 5–10 lines. Add what helps, ignore what doesn’t.\nA Quick Example #One of my scripts takes a Wikipedia article, summarizes it with an LLM, generates voiceover with say, and stitches it into a video with ffmpeg.\nWith no context, the AI kept guessing wrong about which part did what. After adding a one-liner comment at the top (# @ai: summarize → narrate → video), a short ai_context.yml, and a few purpose comments inline, it started suggesting useful edits instead of hallucinating new pipelines.\nThis isn’t magic. It’s just giving the AI a fighting chance.\nWhy This Helps # Fewer repeats – you don’t need to re-explain your project every time Better AI responses – edits are scoped to what you actually meant Scales well – other devs and future you benefit too No lock-in – this works with any LLM, anywhere It’s a small effort with a big return — especially if you use AI tools regularly.\nIf You Want to Try It #There’s a GitHub repo with the v0.1 spec and a starter template.\nIf you\u0026rsquo;re curious:\nAdd an @ai: line to one script header Create a tiny ai_context.yml with the basic flow Run a real AI session against it and see what changes That’s enough to feel the difference.\nOptional: Bootstrap Prompt for Your LLM #In the future, tooling can grab a bootstrap prompt directly from something like ai_bootstrap_prompt.txt.\nFor now, just consider inviting your LLM to work with your code using a quick intro like this:\nThis project follows the AI-maintainable code pattern. It includes structured context files and inline annotations (`@ai:`) to help you understand the project\u0026#39;s purpose, flow, and key relationships. Use those to ground your reasoning before making changes or asking clarifying questions. Final Thought #At the end of the day, LLMs are just machines. If we want useful output, they need useful input.\nStructure matters. Intent matters. And context — more than anything — matters.\n\u0026hellip; Huh. Maybe they\u0026rsquo;re like us, afterall. :)\n","date":"24 March 2025","permalink":"/posts/designing-ai-maintainable-code/","section":"Posts","summary":"How to make your code instantly understandable across LLMs, sessions, and tools. This post explores structure, metadata, and prompts to make AI your pair programmer.","title":"Designing AI Maintainable Code"},{"content":"","date":null,"permalink":"/posts/","section":"Posts","summary":"","title":"Posts"},{"content":"","date":null,"permalink":"/categories/","section":"Categories","summary":"","title":"Categories"},{"content":"","date":null,"permalink":"/tags/","section":"Tags","summary":"","title":"Tags"}]