In my last Log, I expressed how I was confident about something I had no basis for (frankly blind). Realising the folly of my ways, I paused building to audit what I had already built, which was working without any visible flaws. The audit found over 90 security issues and more than 50 poor architectural decisions that any experienced software developer would laugh at.
The entire two-week ordeal made it clear to me that: AI follows my instructions as long as I know the right vocabulary or ideas or concepts. The past two weeks showed how little I knew.
I spent the last two weeks learning new vocabulary, fixing what was broken. After two weeks, my staff did not see any visible changes but underneath, it had changed completely.
At the outset, I knew that things had to change for better or worse. In my previous Log, I spoke about [Cloudflare’s Code Orange project ]((https://blog.cloudflare.com/fail-small-resilience-plan/)and how it inspired me to audit my code. Initially it proved exciting but I realised that I had to explore all possible options.
I took time to understand how software is actually built and maintained in the pre-AI days. During my research, I came across a Youtube Video , which recommended reading John Ousterhout’s “A Philosophy of Software Design”_.
The book explained how complex software projects are actually structured, developed and maintained. My key takeaway from the book: Develop your software based on your workflows and not features.
So far into my app building journey, I did the exact opposite. I spent days thinking about what was needed, slowly morphing O9X as a pile of screens (feature by feature). I found this approach more suited for my use case than Cloudflare’s approach.
Once I finished reading the book, I decided to use the improve-codebase-architecture skill to audit my current app. AI gave me a highly technical document, which I understood maybe 50%; the rest was gibberish to me. Rather than breaking my head on this, I asked Claude Code to restructure the analysis as if my codebase was a company, with each module as a department.
It broke down every module within my app as different departments within a company. I could now understand broken workflows, repetitive work and slacking departments (modules). AI identified over 50 such issues within my codebase.
I had a sloppy API workflow. When AI built the API layer for my app, it replicated the same function and logic across 42 different files (repetitive work). So even one small change in any such function would require changes in 42 files. I was just spending 42 times the tokens needed while cursing at Anthropic for their low usage limits.
Next was extensive use of any (as any can result in my code failing silently without any warning) within my entire code base (broken workflows). I knew about the abuse of any by AI models. I had clear instructions in claude.md to avoid using any. In long sessions, AI simply ignored the instruction, while I congratulated myself for a job well done. I told AI what needed to be done, assuming it always followed my instructions.
Around the same period, OpenAI released a new tool: Codex Security. The tool was built to find, validate, and remediate likely vulnerabilities within any existing codebase. A detailed security audit was next in line but then I decided to use this service to speed up the process.
The first scan identified over 90 vulnerabilities, highlighting the numerous flaws hidden (to me) within my code. The little pride I had in me just left when I saw the report. I had built a boat with numerous holes but due to sheer luck, the boat was floating with no flooding in sight (no vulnerability was exploited).
I decided to tackle the architecture issues first and then fix the security vulnerabilities. I knew that my current workflow was flawed, so it needed to change.
I exported all my highlights and suggestions from John Ousterhout’s “A Philosophy of Software Design” to build a clear design doctrine document. I made a rough draft along with certain ideas and concepts from Cloudflare’s approach. I had AI polish the draft. This document along with improve-codebase-architecture** skill served as the foundations for my new workflow.
Let me walk you through an example that I fixed. My employees check in and check out on O9X and I have a clear geo-fencing policy (blocking if outside pre-defined radius). The database had all the locations and policy was clearly codified. However, I had never codified the constraint inside the check-in function.
For over three weeks, my staff could log in anywhere without any issue (most never did but a few did take advantage). Every time I asked AI to review the check-in function and geo-fencing policy, it reviewed both the modules independently and said no issues. The two modules worked but never spoke to each other.
Over the next week, I started tackling every issue that came about in my audit process: fixing messy code, redesigning certain modules, and building new modules, while documenting every decision. Once all the architecture fixes were made, Codex said that 50 out of the 90 issues were resolved. Clearly good architecture allows for better security, which was something I never knew about.
Fixing the remaining security vulnerabilities was a long and laborious task. New errors kept popping up after every 10-odd fixes.
Despite all the hype and buzz that AI allows anyone to be a software engineer and so on, the last two weeks humbled me. AI was already trained on every error or issue I resolved but I failed to ask the right question. In the end, AI is trained to answer the questions I ask it (it occasionally pushes back).
John Ousterhout’s “A Philosophy of Software Design” and **improve-codebase-architecture** skill gave me a new vocabulary. Once I understood the new vocabulary, my mental models of software systems improved, allowing me to question certain decisions AI was making within my code. I could direct AI to think in a specific direction that ensured it made fewer errors.
My team saw no change in the app, but I know how big a change I made in the past two weeks. The first phase of building O9X was learning how to use AI to build my app. The next phase is understanding software engineering, guiding AI and developing proper checks and balances (It is clear to me now that AI doesn’t always follow explicit instructions). I am still dependent on AI for all the unknown unknowns, and it is a risk I need to live with.