A 3-part playbook for making AI useful on a legacy codebase

A founder reports their AI coding tools repeatedly failed on a three-year-old fintech codebase. The fix involved making implicit knowledge explicit through architectural records, context files, and mandatory tests.

An AI coding assistant was asked to create a new contacts table for a fintech application. It created columns for first name, last name, and email, duplicating fields that already existed in the project's users table. This failure on a three-year-old codebase prompted a shift in strategy. The team stopped asking how to get the AI to write better code and started asking what the AI needed to know to make better decisions.

The problem is common. AI tools excel on greenfield projects but often hallucinate or introduce errors when working with established, complex systems. The author of a post on Dev.to, Jaskiratanand, outlines a process for making a codebase legible to an AI, moving from unreliable output to a dependable workflow. The method is built on providing explicit, authoritative context.

Architectural Decision Records as guardrails

The team created a docs/adrs/ directory to house Architectural Decision Records. These are not general documentation. They are concise files that record the why behind specific technical choices. Each ADR is framed to answer a question a new contributor, human or AI, might have about the project's structure.

Key ADRs answer questions like: How do we structure a new API route? Where do different file types live? How should tables be linked? The contacts table error became the first record, ADR-001. It established a simple rule: check existing tables before creating a new one and use a foreign key if relevant fields already exist. This prevents data duplication and ensures the AI respects the existing database schema.

A context file and project 'plot'

The second step was creating two master documents, context.md and plot.md. The context.md file serves as a glossary for project-specific jargon. It defines terms that a general-purpose AI would misinterpret, clarifying relationships between concepts within the application's domain.

The plot.md file provides a high-level map of the project. It explains what the application does and how its main components connect. Both documents include a critical instruction at the top: the docs directory is authoritative, its rules are not suggestions, and its steps must be followed in order. This primes the AI to treat the provided context as its primary source of truth, overriding its general training data.

Mandatory tests for every new API

Finally, the team made test cases mandatory for every new API route. This rule was non-negotiable and had no exceptions. While primarily a code quality standard, it also serves as a feedback loop for the AI. Tests provide concrete examples of expected inputs and outputs for a given function or endpoint.

By providing a clear definition of 'done' for each task, the tests help constrain the AI's behavior over long sessions. The test suite becomes another form of documentation, one that is executable and unambiguous. It confirms whether the AI-generated code meets the specific requirements of the existing system.

What We'd Change

This playbook's success depends entirely on human discipline. It is a process solution, not a technical one. The system is only as good as the most recent ADR or context file. For a small, co-located team, maintaining this documentation is feasible. For a distributed team of 20 engineers, keeping the context files current becomes a significant operational tax. The playbook works if, and only if, documentation is treated as a core part of the development cycle.

The author frames this as a way to manage AI, but its primary benefit is for human developers. A codebase with clear ADRs, a project glossary, and a complete test suite is easier for any new engineer to join. The AI's improved performance is a secondary effect of creating a more legible and maintainable system for people. The real return on investment is reduced onboarding time and lower key-person risk.

This approach is a prose-based implementation of the same principle behind type systems, popularized by figures like Matt Pocock, whom the author cites. Strong types make implicit contracts explicit in code. ADRs and context files do the same for architectural patterns and domain logic. For teams not using a language with a sufficiently expressive type system, this documentation-first method can provide similar guardrails.

Landing

This is not an 'AI hack.' It is a systematic approach to reducing ambiguity in a software project. The process forces a team to externalize institutional knowledge, making it accessible to any new contributor. The fact that an AI can parse this knowledge is a powerful side effect of good engineering hygiene. The playbook's true value lies in creating a system where the correct way to build is also the easiest way, for both humans and their machine-learning counterparts. The core idea is simple: AI is only as good as the context you give it.

The investor read

This playbook signals operational maturity in a technical team. Investors evaluating early-stage companies should see the implementation of such systems as a strong de-risking indicator. It directly combats key-person dependency, where critical system knowledge resides with one or two senior engineers. A well-documented codebase with clear architectural records lowers the cost of onboarding new talent and makes technical due diligence significantly more straightforward. While not a direct revenue driver, this process discipline reduces the risk of costly bugs, stalled product development, and future rewrites. It suggests a team building for longevity, not just immediate feature velocity. A company that can articulate its 'plot.md' is a company that understands its own business.

Pull quote: “The core idea is simple: AI is only as good as the context you give it.”