DEV Community: davidvk89

I Just Wanted Bannerlord NPCs to Remember Things

davidvk89 — Thu, 02 Jul 2026 15:58:18 +0000

I did not want to write.

I did not want to think.

I did not want to code.

I just wanted Bannerlord NPCs to remember things.

That was the whole crime.

Bannerlord is a strange game for me because it has so much of what I like. Big map. Clans. Armies. Marriages. Trade. Sieges. Prisoners. Fiefs. Lords and ladies with family names, banners, grudges, and theoretically important political ambitions.

It has rich systems.

It also has a world that can feel weirdly dead.

Not bad. Not empty. Just… dead in the specific way sandbox games can be dead. Things happen, but the world does not always seem to understand that they happened. A lord is captured. A battle is won. A marriage is arranged. A village burns. A clan rises. A family member dies.

And then the game politely continues being a spreadsheet wearing armor.

So I started playing with an LLM alongside the campaign.

At first, it was just prose.

And honestly? The prose was the hook.

Suddenly a council scene had weight. A companion could have an opinion. A marriage negotiation could feel like more than a transaction screen. A village notable could become a person with fears, leverage, and memory. A warband returning from a battle could carry more than loot and wounded troops. It could carry consequences.

For a week or two, that was enough.

I was not thinking about architecture. I was thinking, “This is fun.”

Then the magic started fading.

Not immediately. That is the dangerous part. At first, it works well enough to make you believe. Then, a few sessions later, small cracks start showing.

A character remembers something slightly wrong.

Someone knows something they should not know.

A private thought leaks into public dialogue.

A rumor hardens into fact.

A future plan from a planning note starts acting like current canon.

By around session four, the medieval sandbox is no longer a roleplay companion. It is a gossip-powered hallucination engine with horses.

That was the point where I realized the problem was not prose quality.

The LLM could write. That was not the issue.

The issue was memory.

If I wanted the world to feel alive for longer than a few sessions, the characters needed some kind of stable memory. Not just “the whole chat so far.” That would not be enough. Long chats get heavy, messy, and full of things that are not supposed to become true.

The characters needed structured memory.

Who are they? What do they know? What do they believe? What did they witness directly? What were they told second-hand? What is rumor? What is private? What is public? What has happened in the world? What is the current scene? What is the current political situation? What is old enough to matter but not so immediate that it should dominate every conversation?

This was the moment the companion app idea appeared.

The first idea was simple: flat JSON files.

Nothing glamorous. No grand platform. No elaborate database. Just structured files that could hold character memory, world state, campaign events, and useful context.

The important thing was not the storage format. The important thing was that the memory had to be sliceable.

A character should not receive the entire world.

A scout does not need the same context as a spouse. A village elder does not need the same context as a clan council. A captured enemy lord should not know the player’s private plans. A merchant should not suddenly become omniscient because the LLM was given too much campaign history.

The right actor needed the right context packet at the right time.

That sentence sounds boring until you start thinking about multiplayer.

In single-player, a hallucination can sometimes be treated as flavor until it breaks continuity. In multiplayer, it becomes fairness. Hidden information. Player trust. Canon. Authority. Maybe even moderation.

If an LLM says something happened, did it happen?

If an NPC reveals secret information, was that information actually available to them?

If two generated scenes contradict each other, which one is true?

If a player tricks the system into saying something useful, does that become world state?

I needed one exact point where LLM output stopped being suggestion and became truth.

That was the beginning of the trust gate, though I did not have that language yet.

At the time, it was much less dignified. It was more like:

Wait. No. The AI cannot just say that and make it canon.

Very academic.

So the companion app started becoming a memory and context-routing problem. The LLM was not just a writer anymore. It was an actor receiving a bounded context packet and producing output that still needed to be accepted before it changed the world.

Then I asked a coding agent to help build the app.

And within a few prompts, the development process started showing the same disease as the story layer.

The coding agent could move quickly. Sometimes very quickly. It could generate a mockup, create files, wire routes, adjust behavior, and make the thing look like progress.

But it could also grab the wrong idea, preserve a temporary assumption, broaden the scope, or act on something that was only ever meant as background thinking.

That was when the recursion became hard to ignore.

The app needed controlled context so fictional characters would not accidentally act from the wrong memory.

The coding agent needed controlled context so it would not accidentally build from the wrong project understanding.

Same shape. Different layer.

So I started applying the same instinct to the development workflow.

The project documentation became the development equivalent of actor memory. It preserved what the project currently was, what the architecture meant, which data shapes existed, which API contracts mattered, and which ugly things were intentionally deferred.

The Codex Contract became the context packet. Not the whole planning conversation. Not every idea. Not the future dream. Just the bounded implementation slice: what to change, what to preserve, what not to touch, what to verify, what documentation to update, and what to report back.

Final Review became the trust gate. The coding agent’s output was not automatically accepted project state just because it existed. It had to be checked against the contract, tested, reviewed, and folded back into the documentation before it became part of the next cycle’s memory.

In hindsight, this is funny.

I started by wanting Bannerlord characters to remember things.

Then I built memory files for fictional actors.

Then the coding agent building those files needed its own version of memory.

Then the documentation started behaving like project memory.

Then the review step became the point where output became accepted truth.

Then I found myself writing about operational memory, controlled context flow, and trust gates like a person who definitely meant to end up here.

I did not.

This started as play.

Then the toy developed architecture.

This is probably the most honest version of the story:

"I was hooked by the prose first. The serious part came later, because the fun thing had a real problem underneath it. Making an LLM-powered sandbox feel alive is not only a writing problem. It is a memory problem. A context problem. An authority problem."

And, apparently, building the tool to solve that problem creates the same problem one layer up.

That does not mean I solved it. The companion app is still very much a prototype. The workflow is still something I am testing, tightening, and trying not to overclaim.

But the path makes sense to me now.

I wanted NPCs to remember things.

To make that work, I needed structured memory.

To use that memory safely, I needed scoped context.

To make scoped context reliable, I needed review boundaries.

To build the app without losing control of it, I needed the same pattern in my development process.

So yes, I spent a week trying to make AI-assisted development less chaotic.

But the real origin is much less grand than that.

I just wanted Bannerlord NPCs to remember things.

Case File: Context Drift

davidvk89 — Thu, 02 Jul 2026 13:59:00 +0000

A Thought Trail on Operational Memory, Controlled Context Flow, and AI-Assisted Development

I started with what looked like a practical AI coding problem.

The coding agent was moving too fast. Not computationally fast. Conceptually fast. It could turn a loose idea into code before I had fully decided whether that idea was stable, temporary, rejected, or just something I was thinking through.

At first, the obvious suspect was prompting. Maybe I needed clearer prompts, better task descriptions, or more detail each time.

That helped, but it did not explain the whole pattern.

Then documentation looked guilty. If the AI kept losing track of project state, maybe I needed better documentation: cleaner notes, clearer architecture descriptions, more explicit decisions, and more reminders about what not to touch.

That helped too.

But that still was not the whole mechanism.

The problem was not simply that the AI lacked context. The problem was that different parts of the workflow stopped sharing the same understanding of project state.

The human had one version of the project in mind. The assistant had another, shaped by conversation context. The coding agent had another, shaped by the prompt and files it was given. The documentation had another, depending on whether it had been updated. The codebase had the actual state, but not necessarily the intent behind that state.

That gap is what I started calling context drift.

In AI-assisted development, context drift happens when the human, assistant, coding agent, documentation, and codebase stop sharing the same understanding of project state.

When that happens, a coding agent can act on incomplete, stale, speculative, or polluted context faster than the human can mentally reorganize the project.

That was the failure mode.

The AI Did Not Need More Context. It Needed the Right Context at the Right Time.

My first useful response was not “write more documentation.”

It was separating broad reasoning from narrow implementation.

The assistant could reason broadly. It could help explore options, identify risks, compare designs, recover intent, and translate vague thoughts into engineering language.

But the coding agent needed something different.

It needed bounded implementation instructions: what to change, what to preserve, what to avoid, what to verify, what documentation to update, and what to report back.

That pressure eventually became a stricter handoff artifact: a reviewed implementation contract.

In my workflow, I called these Codex Contracts. The name matters less than the role.

The contract was not just a better prompt. It was the reduction point between broad reasoning and narrow execution.

A planning conversation could stay messy. It could include uncertainty, rejected ideas, half-formed thoughts, possible future directions, and things I was not ready to implement.

But the coding agent should not act directly on that whole mess.

The implementation contract translated broad reasoning into bounded authority.

That distinction became one of the most important ideas in the whole project:

Context access is not authority to act.

A coding agent may have access to project documentation, prior discussion, planning notes, future ideas, rejected options, and implementation constraints.

But not all of that context should be allowed to direct implementation.

Useful reasoning context is not automatically implementation authority.

Documentation Changed Role

As the workflow developed, documentation started to change role.

At first, documentation was just helpful notes: architecture notes, current-state summaries, known technical debt, and decisions I did not want to forget.

But once those documents were updated, reviewed, and reused as future context, they became something stronger.

They started functioning as operational project memory.

That does not mean the documentation became source code. It did not compile, execute, or replace tests, code review, or engineering judgment.

But it could guide implementation.

When a coding agent reads documentation and acts from it, documentation becomes part of the instruction surface that shapes future code changes.

That changes how seriously documentation needs to be treated.

A normal bad documentation update is already a problem because it can mislead a human. But in an AI-assisted workflow, a bad documentation update can become bad memory.

If that bad memory is later reused by an assistant or included in coding-agent context, it can preserve false project state and feed it back into future work.

That is why documentation review stopped feeling like cleanup.

It became part of the mechanism.

The documentation had to be required, bounded, reviewed, updated, and reused inside controlled context flow.

More documentation alone was not the answer.

Slow Down the AI, Speed Up the Human

The slogan I kept coming back to was:

Slow down the AI. Speed up the human.

That sounds backwards at first. The whole selling point of AI coding tools is speed. Why slow them down?

Because the AI was already fast.

How the loop works: broad planning context is reduced into a reviewed implementation contract, executed narrowly by the coding agent, reviewed through a trust gate, and preserved as operational project memory for the next loop.

The problem was that it could move faster than I could safely understand, review, and direct. The workflow did not make the AI faster. It made the AI’s speed usable.

By slowing down the transition from reasoning to implementation, I could keep more authority over what the coding agent was actually allowed to act on.

The assistant could help reason, translate, and compress context. The implementation contract could define the task boundary. The coding agent could execute narrowly. Final review could compare the result against the contract. Documentation updates could preserve accepted project state for the next task.

My role shifted away from repeated re-explanation and cleanup, and toward intent, judgment, review, and final acceptance.

That is what “slow down the AI, speed up the human” meant in practice.

The Artifact Trail Mattered

The prototype did not prove that this workflow works generally.

It was one solo prototype, over a short development period, using a prompt-only AI-assisted workflow. It did not test large teams, multiple branches, long timelines, enterprise tooling, or multiple people updating the same project-memory layer.

So the evidence boundary has to stay narrow.

But the prototype did leave something useful behind: an artifact trail.

There were project-memory files, consecutive implementation contracts, documentation updates, final reviews, and later reuse of reviewed context across multiple development passes.

That mattered because the artifacts showed context moving through the workflow.

Broad reasoning did not move directly into coding-agent execution. It was reduced into reviewed implementation contracts. Those contracts acted as the handoff point between assistant reasoning and coding-agent execution.

After implementation, the result was reviewed, documentation was updated, and that reviewed documentation became usable context for later AI-assisted tasks.

That did not make the prototype proof.

But it did make the mechanism visible.

The value of the prototype was not that it answered the scale question.

The value was that it made the scale question concrete enough to ask.

This Is Not a Claim of Inventing Software Engineering

A fair critique is that none of this sounds completely new.

Specifications, reviews, architecture decision records, acceptance criteria, technical-debt tracking, implementation boundaries, and living documentation all existed before this.

I am not claiming otherwise.

The interesting question is narrower:

Do familiar software-engineering practices take on a different operational role when arranged around AI-assisted development, where assistants and coding agents may read, reuse, and act on project context?

In my prototype, the answer appeared to be yes.

Documentation was no longer only explanatory. It became operational. It became part of the memory layer.

Controlled context flow became the routing and authority layer.

The implementation contract became the reduction point between broad reasoning and narrow execution.

Review before reuse became the safety gate before documentation could become trusted future context.

The pieces were familiar.

The arrangement mattered because the failure mode was specific to AI-assisted development.

The problem was not only whether the AI had enough context.

The problem was whether the AI was acting from the right context, at the right time, with the right authority.

Better Tools Do Not Remove the Principle

Manual file passing was part of my prototype, but it was never the principle.

I manually dragged files around because that was what my tools allowed and because I wanted direct control over what context went where.

A better tool should reduce that manual overhead. Repo-aware coding agents should be able to inspect files, retrieve documentation, index project state, understand code structure, and work directly inside development environments.

That is the better direction.

But repo awareness does not remove the deeper problem.

Access to more context is not the same as controlled context flow.

A repo-aware agent with broad access can still act from the wrong context if it treats unreviewed planning, stale documentation, rejected ideas, or future possibilities as actionable implementation instruction.

That is why the principle is not manual file separation.

The principle is controlled separation between reasoning context, reviewed project memory, implementation authority, coding-agent instructions, documentation updates, and future reusable context.

Better tooling should reduce manual overhead while preserving or strengthening those control points.

The Security Turn

The final clue was not another workflow improvement.

It was the risk hiding inside the improvement.

If documentation could become operational project memory, then documentation was no longer only a record of the project. It could become part of the instruction surface future AI-assisted work relied on.

Not executable code.

Not a replacement for tests, review, or engineering judgment.

But still something that could influence future code changes.

That changed the case.

A bad documentation update was not just a bad note anymore.

If it passed review and entered future context, it could become bad memory.

If a coding agent treated that memory as implementation guidance, then misleading or poisoned documentation could shape code without anyone directly changing the source code.

This was not a newly discovered attack class. It belonged to a known family of LLM security risks showing up inside the mechanism.

OWASP describes indirect prompt injection as occurring when an LLM accepts input from external sources such as websites or files, and notes that the impact depends partly on the agency built into the system. OWASP lists possible impacts including unauthorized function access, arbitrary command execution in connected systems, and manipulation of critical decisions. (OWASP Gen AI Security Project)

OWASP’s prompt-injection prevention cheat sheet also lists RAG poisoning/retrieval attacks and agent-specific attacks among common attack types. (OWASP Cheat Sheet Series)

In my project’s terms, the risk is this:

A bad actor may not need to attack the source code directly.

They may attack the project memory layer that future AI-assisted work relies on.

That made the old distinction sharper:

Documentation access is not implementation authority.

A coding agent may be able to read broad project documentation.

That does not mean every sentence inside it should be allowed to guide implementation.

Trust Gates

This is where the trust gate mattered.

A trust gate is the point where context becomes more authoritative than it had been before.

Planning context becomes implementation authority. Draft documentation becomes operational project memory. Coding-agent output becomes accepted project state.

A future tooling system might implement that with permissions, review workflows, provenance checks, authority labels, policy enforcement, or some better mechanism I have not designed.

In my prototype, the trust gate was crude and manual.

It was me dragging files.

It was me deciding what crossed the boundary.

It was me deciding what stayed background context, what became implementation instruction, and what the coding agent was actually allowed to act on.

In hindsight, manual file dragging wasn't just awkward tooling.

It was a crude chain of custody.

That is why the detective metaphor started to fit.

The important question was not only:

What does the AI know?

It was:

Where did this context come from?

Has it been reviewed?

What authority does it have?

What is allowed to act on it?

What happens if it is wrong?

That is not just a workflow question.

At scale, it becomes a security and governance question.

The Limit of the Prototype

This is also where the prototype reaches its honest limit.

The artifact trail can show the mechanism. It can make the workflow inspectable. It can explain why documentation, controlled context flow, implementation authority, and review before reuse mattered in one observed workflow.

But it cannot prove safety at scale.

The same property that makes operational documentation useful also makes it sensitive.

If it can preserve project intent, it can also preserve false authority.

If it can help guide future implementation, it can also misguide future implementation when stale, poisoned, or poorly reviewed.

If this mechanism scales, then documentation governance becomes part of the safety model.

Projects would need to know which documents are passive explanation, which are planning-only, which are trusted operational memory, and which are allowed to become implementation authority. They would need provenance, ownership, review rules, stale-memory detection, conflict reporting, and better tooling around context routing and agent authority boundaries.

That is bigger than one solo prototype.

And that is the point.

What I Think I Found

I do not think I proved a finished methodology.

I do not think I proved long-term project memory.

I do not think this exact workflow should be copied unchanged.

What I think I found is a prototype-scale mechanism:

Documentation-as-operational-memory, when maintained through controlled context flow, may support long-term project memory in AI-assisted development.

That is a hypothesis, not a conclusion.

The prototype supports a narrower claim:

In one prompt-only AI-assisted development workflow, this mechanism appeared to reduce context drift and make later work more reviewable, bounded, and easier to resume.

That is enough to make the mechanism worth testing.

It is not enough to declare it solved.

The next work belongs to larger projects, longer timelines, multiple agents, team workflows, repo-aware tooling, and better security testing.

The case stops being only mine at exactly the point where the implication becomes too large to validate honestly alone.

That is not a failure of the prototype.

That is the research boundary.

The prototype found a mechanism specific enough to inspect. The artifact trail makes it possible to challenge. The hypothesis is clear enough to test.

Scaling it belongs to better tooling, better security boundaries, and more rigorous testing than one person can honestly provide.

From Vibes to Project Memory

davidvk89 — Tue, 30 Jun 2026 14:06:11 +0000

That is the full set published.

I did not write these articles because I think I found the final answer to AI-assisted development.

I wrote them because I spent one serious week building with AI, ran into context drift almost immediately, and found a small workflow that made the project feel less fragile.

The three pieces ended up covering the same idea from different angles:

Vibe Coding Done Right — the workflow
Documentation as Project Memory in AI-Assisted Development — the memory system
Defensive AI Engineering — the objections and limits

Together, they trace the thing I was really trying to do:

move from vibes to memory.

From a messy human experience with AI tools into written documentation, bounded contracts, and a workflow I could actually inspect.

The supporting GitHub repo is there too, not as a framework or package, but as the artifact trail from the case study.

The main thing I learned is still simple:

AI-assisted development is not only a coding problem.

It is a context management problem.

For me, the useful pattern became:

Explore in conversation.

Build from a contract.

Preserve the result in documentation.

Reuse that documentation as context for the next task.

The result was not perfect AI coding.

The result was reviewable AI coding.

That was the part worth writing down.

I’m going to leave the series there. It was a one-week field report, not a manifesto. Maybe I will come back to the ideas later after using the workflow more, maybe I will not.

For now, it exists. That was the goal.

Thank you to everyone who read, skimmed, questioned, or followed along.

And if you made it all the way through the series: genuinely, thank you for making it this far.

If there is one sentence behind the whole project, it is this:

Slow down the AI. Speed up the human.

The AI does not need help moving faster. The human needs enough structure to stay in control.

Defensive AI Engineering

davidvk89 — Tue, 30 Jun 2026 13:43:50 +0000

When you tell developers that my solution to AI context drift was keeping four live markdown files updated alongside every code change, the reaction is entirely predictable:

“You’ve just traded code debt for documentation debt. This kills velocity.”

Or, from the IDE-purists:

“Why are you manually passing files around when native agents can scrape your whole repo?”

These are fair critiques.

If you treat documentation as a post-work chore or rely blindly on an autonomous agent to manage its own sandbox, the system collapses under its own weight.

But the TB / CC / FR loop — Task Brief / Codex Contract / Final Review — is not a bureaucratic process. It is a defensive pattern.

Coming from a background in cybersecurity, my default mode of operating is isolation, strict boundary enforcement, and assuming the agent will misbehave if given loose permissions.

This was the solution that fit my project, my tools, and my risk tolerance. The useful part is not that every developer should copy my exact setup. The useful part is that the pattern can change shape depending on the team, tooling, and codebase.

Here is how the project memory loop holds up against the four harshest criticisms of AI-assisted engineering.

1. The "Documentation Tax" Can Be Shifted, Not Removed

The Critique: Maintaining four separate documentation files — DEV_ARCHITECTURE.md, DEV_DATA_SHAPES.md, DEV_API_CONTRACTS.md, and TECHNICAL_DEBT.md — for every meaningful code change creates a bottleneck.

The Reality: The human developer does not need to write most of the documentation manually.

In this workflow, documentation is a required transactional output of the implementation contract. Because the context memory is defined during the Task Brief and refined into a bounded Codex Contract, the coding agent is the one tasked with updating the relevant markdown files.

The human’s job is to act as editor and gatekeeper during Final Review, verifying the AI’s reported documentation updates against the actual code changes.

That still costs attention. It is not free.

But the cost moves from “remember everything later and write documentation someday” to “review the documentation while the task context is still fresh.”

You are not eliminating the documentation tax. You are turning it into a reviewable part of the implementation transaction.

2. The Case for Separated Context

The Critique: Manually passing project files into an assistant or switching between an assistant and a coding agent feels primitive when IDE-integrated tools can auto-index a codebase.

The Reality: Full-repository context is convenient, but convenience is not the same thing as control.

The important separation in this workflow is not physical air-gapping. It is memory separation.

The assistant can operate from broader project memory: architecture, tradeoffs, future direction, unresolved concerns, and the reasoning behind the current shape of the system.

The coding agent should not automatically receive all of that.

The coding agent should receive the bounded implementation slice: what to build, what to preserve, what not to touch, which files are likely involved, what documentation must be updated, and how to report back.

That is the purpose of the Codex Contract.

The CC acts as a translation layer between broad architectural thinking and narrow implementation work. It lets the assistant help preserve strategy and future direction without creating a route for the coding agent to start building future ideas too early.

A planning conversation can contain useful context that is dangerous implementation context.

“This might become a system later” is useful for architectural memory.

It is not useful as permission for the coding agent to start building that system now.

By keeping assistant memory and coding-agent context separate, the workflow forces intentionality. The coding agent only receives the implementation details and documentation updates that belong in the current task.

That keeps it in executor mode rather than co-architect-with-selective-memory mode.

3. Grading the Homework: Mitigating AI Hallucinations

The Critique: You cannot trust an AI to verify its own work or accurately report that it updated the documentation correctly. LLMs are notoriously prone to sycophancy.

The Reality: Correct.

LLMs will absolutely grade their own homework poorly if left unsupervised.

That is exactly why the Final Review stage relies on strict human acceptance and manual testing.

The assistant can assist in reviewing the coding agent’s return, but it does not replace human verification. The human remains the ultimate source of truth for scope and risk.

Furthermore, every software engineering methodology has a single point of failure: the human developer.

If a human engineer experiences a lapse in judgment, a critical oversight, or a medical emergency, the system breaks.

The loop does not assume the AI is perfect.

It assumes the AI is volatile, and creates a rhythm to catch mistakes before they are born.

4. The Scale Bottleneck: Moving Beyond the Prototype

The Critique: This works for a solo developer handling local JSON persistence. On an enterprise team with dozens of developers working on different branches, simultaneously modifying core markdown files will cause catastrophic Git merge conflicts.

The Reality: This is a completely accurate limitation of the manual prototype.

For a solo project, dragging files into a browser provides a simple, zero-cost map.

For a sprawling, multi-developer enterprise repository, the method would need to evolve from manual file handling to an automated tooling layer.

The architectural blueprint to solve this likely requires two next-generation components:

The Memory Controller: a system utility that programmatically parses, slices, and modularizes the core documentation files based on directory domains, feeding the LLM a compressed context packet rather than the entire repo documentation history.
The Semantic Diff Validator: a verification gate that compares the old documentation state against the new state, isolating the structural variance and presenting the human reviewer with a focused slice to approve or reject during pull requests.

Until better tooling exists around this kind of workflow, teams will have to adapt to these branching realities.

But the underlying principle remains useful:

AI-assisted development becomes safer when project memory is explicit, implementation context is bounded, and human review remains the final gate.

Conclusion

Defensive AI engineering means accepting a simple truth:

AI coding agents are incredibly fast, but they are strong enough to cause damage before lunch if left unconstrained.

The TB / CC / FR loop is not about slowing down development for the sake of process.

It is about establishing reviewable guardrails so that velocity does not turn into chaotic drift into the fog.

By treating documentation as a live transaction, keeping assistant memory separate from coding-agent context, and forcing human sign-off, you keep the human firmly in control of the codebase.

Author’s note

Small clarification on the intent behind this article:

I am not claiming that the individual mechanics here are new.

Specs, reviews, ADRs, acceptance criteria, technical debt tracking, and living documentation all existed before this. I am not institutionally trained as a software engineer, so I fully expect overlap between the names I used and the names the industry already has for similar practices.

One of the strongest gains I found in the AI-assisted workflow was that the assistant helped translate my more natural, experience-based language into precise engineering terms. I could start with “this feels unsafe” or “the AI might build the wrong thing,” and refine that into ideas like scope boundaries, trust boundaries, implementation contracts, and project memory.

So the naming is personal.

The underlying problem is not.

The problem is context memory: AI coding agents can act on incomplete, stale, speculative, or polluted context faster than the human can reorganize the project mentally.

My claim is not that I invented the individual mechanics.

My claim is that treating documentation as required implementation output can turn documentation into reusable project memory for AI-assisted development.

That worked at prototype scale for me. I hope people with deeper engineering experience and better tooling can test, challenge, adapt, and harden the same idea at larger scales.

Documentation as Project Memory in AI-Assisted Development

davidvk89 — Tue, 30 Jun 2026 13:26:14 +0000

A practical case study in keeping AI-generated software bounded, reviewable, and maintainable.

Summary

AI-assisted development has a context problem. Coding agents can implement quickly, but they depend heavily on the context they receive. A long planning conversation is often poor implementation context: it may contain rejected options, future ideas, shorthand, loose assumptions, and half-decisions.

For a human, that is normal design exploration. For a coding agent, it can become accidental permission.

This case study describes a workflow for reducing that risk by treating documentation as project memory. The implementation was tested under a strict constraint: every code change in the project went through the AI-assisted workflow. I did not write code directly, even when it would have been faster.

The core pattern is:

Explore in conversation. Build from a contract. Preserve the result in documentation. Reuse that documentation as context for the next task.

The case study is intended to be read alongside the project documents and three consecutive Codex Contracts:

DEV_ARCHITECTURE.md
DEV_DATA_SHAPES.md
DEV_API_CONTRACTS.md
TECHNICAL_DEBT.md
CP-0011.txt
CP-0012.txt
CP-0013.txt

Together, these documents show the method operating across a short development sequence rather than a single isolated task.

Problem: context decay

The practical risk in AI-assisted development is context decay: decisions are made faster than they are preserved.

Architecture, API behavior, data shapes, validation rules, temporary compromises, and deferred work can disappear into chat history or human memory. Once that happens, later tasks start from incomplete or stale context.

The solution in this implementation was to make documentation part of the development transaction.

Documentation is not written “after the work.” It is a required output of the work.

If a task changes architecture, the architecture document changes. If it changes an API response, the API contract changes. If it changes stored data, the data shape document changes. If it exposes a problem that should not be fixed yet, the technical debt document changes.

In this project, the main memory files are:

DEV_ARCHITECTURE.md
DEV_DATA_SHAPES.md
DEV_API_CONTRACTS.md
TECHNICAL_DEBT.md

These files are operational project memory. They preserve decisions, constrain future work, and provide current context for later AI-assisted tasks.

Implementation: TB / CC / FR

The workflow uses three stages:

Task Brief: explore the problem.
Codex Contract: define the bounded implementation.
Final Review: check the result and update project memory.

The control model is two-way review: the human reviews the AI’s output, and the assistant reviews the human’s instructions for ambiguity, scope creep, and loose language. The human decides when the contract is clear enough to hand off, and when the result is acceptable.

In practice:

explore → contract → review → implement → test → review result → patch code or docs → continue from updated documentation.

Task Brief

The Task Brief is where the task is explored before it becomes implementation work.

The goal is to identify scope, risks, constraints, non-goals, affected files, expected behavior, and documentation impact.

This stage may include uncertainty, alternative designs, and questions. It is not sent directly to the coding agent.

The assistant is useful here as a reviewer and translator. It helps convert engineering instincts into clearer technical language:

“This feels unsafe” becomes “this crosses a trust boundary.”
“Do not save failed AI output” becomes “protect the validation and commit boundary.”
“This ugly thing should not be fixed now” becomes “record it as technical debt and keep it out of scope.”

The output of the Task Brief is not code. The output is a clearer implementation target.

Codex Contract

The Codex Contract is the bounded instruction set given to the coding agent.

It is not a transcript of the planning conversation. It is the cleaned-up implementation contract.

A good contract states:

the goal;
relevant context;
files likely involved;
behavior that must be preserved;
non-goals;
acceptance criteria;
verification steps;
required documentation updates;
final report requirements.

The non-goals are critical.

With coding agents, “do not do this” is often as important as “do this.” If the contract does not explicitly say not to refactor a legacy route, the agent may refactor it. The refactor may be technically reasonable and still be wrong for the current task.

The contract defines the box.

Documentation updates are part of that box.

Final Review

Final Review checks both implementation and memory.

The review asks:

Did the implementation match the contract?
Did it preserve required behavior?
Did it avoid unrelated changes?
Did it update the correct documentation?
Did it record deferred work as technical debt?
Did the report accurately describe what changed?
Does anything need a bounded patch?

Manual testing remains required. The assistant can help review the coding agent’s return, but it does not replace human acceptance.

The workflow is therefore not:

Write code, then someday update docs.

It is:

Design the slice, implement the slice, update the docs, review the result, patch if needed, repeat.

That is the mechanism that turns documentation into project memory.

Why contract review matters

The contract review step exists because conversational language can leak into technical instructions.

A simple example from this case study is the phrase “dynamic frontend.” In conversation, that is understandable shorthand. The project has a browser interface with dynamic behavior: polling, player input submission, scene rendering, choices, Chronicle rendering, and rollback wiring.

But the project-memory wording is more precise:

a static browser frontend served by the Node backend, with dynamic client-side behavior owned by public/app.js.

That distinction matters. In a CC, “dynamic frontend” could be misread as permission to introduce a frontend framework, server-side rendering, a build step, or a broader UI restructure. None of that is intended.

This is exactly the failure mode the workflow is designed to catch. Human shorthand is useful during exploration. It must be cleaned up before implementation.

Representative sequence: CP-0011 to CP-0013

CP-0011, CP-0012, and CP-0013 are included as three consecutive Codex Contracts from the same development phase.

They are useful together because they show the workflow being applied repeatedly across different kinds of context work:

CP-0011 establishes a narrow Thread Context Controller v0.
CP-0012 establishes a Messages Side Channel v0.
CP-0013 deprecates legacy Enforcement data and adds clean scoped Enforcement v0.

The details differ, but the contract pattern is the same. Each task defines a bounded implementation, preserves legacy behavior, names what must not be changed, gives acceptance criteria, requires verification, and tells Codex what to report back.

CP-0013 is the strongest documentation-memory example because it explicitly requires narrow updates across:

DEV_DATA_SHAPES.md
DEV_API_CONTRACTS.md
DEV_ARCHITECTURE.md
TECHNICAL_DEBT.md

The sequence matters. It shows that documentation as project memory was not a one-off instruction. It was part of the operating pattern across consecutive development passes.

Example pattern

Assume a feature is hardcoded in a legacy file. It should eventually become a cleaner system, but the current task should only create a safe v0 seam.

A weak instruction would be:

Refactor this feature into a better system.

That instruction has no boundary.

A better Task Brief clarifies the scope:

We are not building the full system yet. We are creating a clean v0 seam. The old legacy data must remain. The new code should read clean records, skip legacy records, and expose a separate API field. No migration. No deletion. No broad refactor.

The Codex Contract turns that into implementation instructions:

Create a controller for clean v0 records. Preserve the old API field. Add a new clean projection. Do not rewrite existing files. Do not change JSON loading behavior. Do not refactor unrelated legacy routes. Update architecture notes, API contracts, data shapes, and technical debt only where this task changes them. Report changed files, validation rules, documentation updates, and risks.

Now the coding agent has a bounded task. It knows what to build, what not to touch, where documentation belongs, and what to report back.

Final Review then checks the implementation, the report, and the documentation updates. Any correction goes back through the loop as a bounded patch.

Why it works

This pattern works because documentation becomes part of the development transaction.

The documents are updated while the context is fresh. The coding agent receives a bounded contract instead of a messy conversation. The assistant can reason from current project documents instead of stale chat history. The developer does not have to keep the whole system in working memory.

The result is not perfect AI coding.

The result is reviewable AI coding.

A change can be evaluated against the contract. A working implementation can still be rejected if it violates scope. Deferred work can be preserved without being accidentally implemented. Future tasks can begin from documented project state.

Scope

The implementation described here was built as a local prototype with:

Node backend;
static browser frontend with dynamic client-side behavior;
local JSON persistence;
rollback support;
validation gates;
LLM gateway compatible with local or OpenAI-style providers.

ChatGPT was used for planning, review, and learning. Codex was used as the coding agent. LM Studio was used for local model testing.

The exact tools are not the important part.

The transferable pattern is:

conversation for exploration, contract for implementation, documentation for memory.

Under this implementation, documentation acted as project memory because three conditions were enforced:

documentation updates were required by the implementation contract;
documentation updates were checked during final review;
updated documentation was reused as context for later tasks.

The workflow does not remove the need for human judgment. It depends on it. The human still owns scope, acceptance, risk decisions, and final review.

Conclusion

Documentation as project memory is a practical control mechanism for AI-assisted development.

The value is not that documentation exists.

The value is that documentation becomes operational.

It constrains the next task, preserves decisions, records deferred work, and reduces dependence on chat history or human memory.

That is what kept the project understandable under a prompt-only implementation constraint.

davidvk89 / ai-project-memory-loop

A lightweight workflow for using live project documentation as memory in AI-assisted development.

ai-project-memory-loop

Supporting files for a one-week case study in using live project documentation as memory during AI-assisted development.

This repository is not a framework, package, or complete methodology. It is the artifact trail behind three companion articles about keeping AI-assisted development bounded, reviewable, and human-led.

Core idea

AI-assisted development has a context problem.

Coding agents can move quickly, but they only work from the context they are given. A long planning conversation can contain rejected ideas, shorthand, future plans, temporary assumptions, and half-decisions. For a human, that is normal design exploration. For a coding agent, it can become accidental permission.

The workflow documented here uses a lightweight loop:

Task Brief      -> explore the problem
Codex Contract  -> define the bounded implementation
Final Review    -> test, inspect, patch, and update project memory

The project memory files are updated as part of the work, not someday after the work. That gives the…

View on GitHub

Vibe Coding Done Right

davidvk89 — Tue, 30 Jun 2026 13:13:43 +0000

Or: spec-driven AI-assisted development for solo developers.

I did not set out to invent a software development workflow. I was trying to build a small local app with AI help, learn as I went, and avoid turning the project into a mysterious pile of files that technically ran but could no longer be explained by anyone involved.

AI coding tools are powerful. They can generate code quickly, refactor without getting bored, write boilerplate, spot patterns, and produce useful documentation. They can also confidently make changes that are almost right, broaden the scope, fix things you did not ask them to fix, or “helpfully” redesign a part of the system you were trying to keep boring.

For a solo developer, that creates a practical problem. The AI can move faster than your ability to keep the project organized. At first, this feels like productivity. A few sessions later, you may be staring at a codebase wondering when the raccoon got into the wiring.

The issue is not that the AI is bad. The issue is that AI-assisted development needs structure. Not heavy enterprise-process structure. Just enough structure to separate thinking from building, and building from review.

Spec-driven does not mean big upfront design. It means writing just enough specification before spending coding-agent credits.

The casual name is the TB / CC / FR loop:

TB: Task Brief
CC: Codex Contract
FR: Final Review

After introducing those names, I just call it the loop.

In my workflow, ChatGPT is the assistant: planner, tutor, reviewer, and sometimes patient explainer of software engineering terms I probably should have known already. Codex is the coding agent: the builder that gets the final bounded contract.

That separation matters. The assistant can help me think through the mess. Codex should get the cleaned-up version.

My stack

This workflow did not come from an expensive or exotic setup.

My stack is practical:

Windows as my main environment
ChatGPT Plus in the browser for planning, review, and architectural discussion
Codex through its desktop client as the coding agent
PowerShell for running the project and checking output
Visual Studio Code with the codebase open beside everything
LM Studio running a local LLM so I can test my application layer without needing a paid API key for every experiment

LM Studio is useful because I am building an app that talks to a language model. I need to test that loop often. Running a local model lets me test rough application behavior without worrying that every broken model response or half-working route is costing money through an API.

Codex credits matter too. Burning through them because I handed the coding agent a vague contract is not just wasteful; eventually, you run out. That is one reason I started separating architectural discussion from implementation. ChatGPT can help me think, review, and refine the task. Codex should get the bounded contract that is actually ready to build.

This is not a luxury AI engineering stack. It is one paid subscription, local tooling where possible, and a workflow that tries to make the most of both.

Why solo AI coding gets messy

When I started using AI to help build my project, the temptation was simple: explain what I wanted, let the coding agent make changes, test the result, then continue.

That works for tiny changes. It does not scale well once the project starts developing architecture.

Software projects are full of invisible context:

This part is temporary.
This ugly thing is legacy, but still required.
This file should not become a dumping ground.
This route must preserve its API contract.
This data shape is intentionally minimal.
This feature sounds useful, but it belongs later.
This bug should be fixed, but not inside this task.

A human developer on a team may know this from conversations, code reviews, planning meetings, or institutional memory. A coding agent does not have stable shared context unless you give it one.

But giving it everything creates a different problem. The agent may grab onto the wrong idea from earlier discussion and implement something half-decided, future-facing, or experimental.

So the trick is not “give the AI everything.”

The trick is to give the AI the right bounded slice.

The loop

The loop separates the work into three stages.

A TB, or Task Brief, is where I think through the problem. This is the design space. What are we trying to do? Why does it matter? What are the risks? What does this touch? What should we avoid? Are we building the real system, or just an extension point for the future?

This is the place for discussion, uncertainty, and tradeoffs.

A CC, or Codex Contract, is the reviewed instruction set that Codex receives.

This is not the place for brainstorming. This is the place for instructions.

An FR, or Final Review, happens after Codex reports back. This is not the same kind of review as the CC review. The CC is rigorously reviewed before Codex builds. The FR happens after Codex is done: I manually test the feature, inspect the result, and have the assistant check Codex’s return against the contract.

This is where the human stays in charge.

The loop is:

Think through the task → write the CC → review the CC → let Codex build → manually test and review Codex’s return → patch if needed → move to the next slice.

That may sound formal, but in practice it is lightweight. It keeps the project from becoming a long improvisation session where every step technically makes sense but the whole thing slowly loses shape.

The CC is the contract

The CC is the heart of the workflow.

A good CC is not just a set of instructions. It is a small implementation contract.

It should include:

the goal
current context
known legacy behavior
non-goals
likely files involved
rules that must not be broken
acceptance criteria
verification steps
final report requirements

The non-goals are especially important.

With AI coding, “do not do this” is often as valuable as “do this.” If you do not explicitly say “do not refactor this legacy route,” there is a real chance the agent will decide the route looks messy and try to improve it. Sometimes it will even be right that the code is messy. That does not mean it belongs in the current task.

A CC gives the coding agent a box to work inside.

The box is not there because the agent is weak. The box is there because the agent is strong enough to cause damage quickly.

Review the CC before handing it off

One part of the workflow that matters more than I expected is reviewing the CC before giving it to Codex.

At first, I thought of the CC as something I wrote and then sent. Now I treat it like a small design artifact that deserves review before it becomes implementation fuel.

My process is simple. I read the CC myself while also having the assistant review it. I look for context I do not want Codex to act on. If I see future ideas, speculative comments, or background discussion that should not become code, I remove it or mark it clearly as out of scope.

At the same time, I ask the assistant to look for ambiguity, missing constraints, contradictions, and places where Codex might reasonably misunderstand the task. If the review brings up a good point, I patch the CC before committing it to Codex.

Sometimes this takes one review. Most of the time it takes two. For larger architectural tasks, it may take four or five passes.

That is not wasted time. It is much cheaper to patch a contract than to untangle an implementation that faithfully followed a bad one.

The question is not only: does this contract describe what I want?

It is also: does this contract contain anything I do not want Codex to treat as permission?

That second question matters a lot.

AI coding agents are good at picking up intent, but they are not always good at knowing which parts of a conversation were final, deferred, speculative, rejected, or just me thinking out loud. Reviewing the CC creates a checkpoint between design discussion and implementation.

In normal software development, code review happens after someone writes code. In this workflow, contract review happens before the AI writes code. It does not replace implementation review, but it prevents a surprising number of mistakes from being born in the first place.

Keep the coding agent’s context clean

The coding agent does not need the entire conversation history.

That is intentional.

The broad architectural discussion happens elsewhere. The CC is the distilled result. It gives Codex just enough context to implement the task without dragging in every idea, doubt, future feature, and half-joking comment that came up during planning.

This separation matters because solo developers often think through projects conversationally. That is useful. It is also messy. A conversation can contain today’s plan, tomorrow’s idea, a rejected approach, a metaphor, and a possible future feature that should not be touched for three months.

You do not want all of that in the implementation context.

Instead, Codex should receive something closer to:

Here is the task. Here is the boundary. Here are the contracts. Here is what success means. Here is what you must not touch. Report back when done.

That keeps Codex in executor mode rather than co-architect-with-selective-memory mode.

Documentation is project memory

This workflow depends on good documentation, but not the ceremonial kind.

I am not talking about writing a polished manual nobody reads. I mean living project documents that help make the next decision.

This may be the most important part of the method: with the right CC, the documentation starts to write itself.

I do not manually write most of my documentation. The CC tells Codex which documentation files to update and what kind of change belongs where.

In my project, that usually means:

DEV_ARCHITECTURE.md
DEV_DATA_SHAPES.md
DEV_API_CONTRACTS.md
TECHNICAL_DEBT.md

If we discuss architecture during the TB, the CC tells Codex to update DEV_ARCHITECTURE.md. If the implementation changes an API response, the CC tells it to update DEV_API_CONTRACTS.md. If a data shape changes, it belongs in DEV_DATA_SHAPES.md. If something is intentionally deferred, it goes into TECHNICAL_DEBT.md.

I do not usually review the documentation line by line myself. The Final Review is based on Codex’s return: what files it changed, what behavior it implemented, what it says it verified, and what documentation it reports updating.

Most of the time, I have the assistant review that return and check whether the reported documentation updates match the CC and the implementation summary. If something is missing, too broad, or in the wrong document, I ask for a patch and send that back through the loop.

So the workflow is not:

Write code, then someday write docs.

It is closer to:

Design the slice, build the slice, have Codex update the docs, review Codex’s return, patch if needed, repeat.

These documents are not just for future users. They are for me, for the AI assistant, and for the project itself.

For me, they reduce the amount I have to keep in my head. I can check what the system currently promises, what is legacy, what is intentionally deferred, and what should not be touched yet.

For the AI assistant, they provide current project memory. I can feed the docs into ChatGPT and it can reason from the latest architecture instead of guessing from stale conversation history. That makes the next TB or CC sharper because the assistant is working from documented project truth, not vibes.

For the project, the docs act like a stabilizer. They guide contracts, preserve decisions, and make technical debt explicit. TECHNICAL_DEBT.md is especially useful. It lets me say, “Yes, this is ugly. No, we are not fixing it in this task.”

The docs also solve a practical problem with long AI chats. Eventually, a long conversation can become slow, heavy, or awkward to continue. If the project memory only lives in that chat, starting fresh means losing context. But if the docs are up to date, I can open a fresh chat, upload the docs, add a short context packet, and continue from a clean starting point.

That turns documentation into long-term memory.

Good docs turn the project from a memory test into a map. A sharper map makes the CC sharper. A sharper CC makes the implementation safer. A safer implementation makes the docs easier to update.

That is the loop beginning to reinforce itself.

Use the assistant to learn, not just brainstorm

The assistant is not only there to brainstorm features or polish contracts. For me, it is also part of the learning process.

I am not approaching the project as someone who already knows every software engineering pattern by name. A lot of the value comes from asking what something is called, why a design feels risky, what tradeoff I am making, or how an experienced engineer would describe the problem.

That turns the assistant into more than a planning partner. It becomes a tutor, translator, and reviewer.

Sometimes I ask for the industry term. Sometimes I ask for the simple version. Sometimes I ask for the “software engineer review” of an idea that feels right but may have hidden problems. That is how vague instincts become clearer concepts.

There is one trick I found useful: sometimes you have to be strict with your assistant.

If the answer starts drifting, getting too soft, or turning into pleasant brainstorming when I need implementation discipline, I say something like:

“Review this like a software engineer.”

Or:

“Write the CC like a software engineer.”

That kind of instruction helps reset the tone. It tells the assistant to stop being encouraging for a moment and start looking for ambiguity, missing constraints, scope creep, and failure modes.

That is important for a beginner mindset. Beginner-friendly does not mean vague. It means clear enough that you can learn without pretending you already know everything.

A small example

Imagine you have a feature that is currently hardcoded in a messy legacy file. You know it needs to become a clean, reusable system eventually. The tempting AI instruction is:

“Please refactor this feature into a better system.”

That is dangerous. “Better” can mean anything.

A TB would first clarify the actual goal:

“We are not building the full system yet. We are creating a clean v0 seam. The old legacy data must remain. The new code should read clean records, skip legacy records, and expose a separate API field. No migration. No deletion. No broad refactor.”

Then the CC would translate that into implementation instructions:

“Create a controller for the clean v0 records. Preserve the old API field. Add a new clean projection. Do not rewrite existing files. Do not change JSON loading behavior. Do not refactor unrelated legacy routes. Add docs. Report changed files, validation rules, and risks.”

Before sending that CC, I would review it. If it included a paragraph about future advanced filtering, and I did not want that implemented yet, I would remove it or put it under non-goals. If the assistant pointed out that “clean projection” could be confused with “LLM context,” I would patch the CC to define those as separate outputs.

Only then would I hand it to Codex.

The result is not glamorous, but it is safe. And safe is underrated when you are building with tools that can rewrite half your project before lunch.

Why this helps solo developers

Solo developers have an unusual burden. You are the product owner, architect, developer, tester, reviewer, and documentation department. Now, with AI, you may also be managing one or more very fast assistants.

The loop helps because it creates a small team structure even when you are working alone:

You, during TB: architect
You, reviewing CC: editor and risk filter
ChatGPT: tutor and reviewer
Codex: implementer
Docs: shared memory
You, during FR: tester and reviewer

That separation makes the work feel less like constantly reacting and more like moving through deliberate slices.

When you are learning, you do not always know the perfect architecture upfront. That is fine. The point is not to be a senior engineer cosplaying as a process consultant. The point is to slow the project down just enough that you can understand what changed and why.

A beginner-friendly workflow should not require pretending to know everything. It should make uncertainty manageable.

The real benefit

The real benefit of this workflow is not that it makes AI coding perfect. It does not.

The benefit is that it makes AI coding reviewable.

You can compare the implementation against the CC. You can test the feature manually. You can have the assistant review Codex’s return. You can update the docs. You can reject a change for violating scope even if the code works. You can preserve decisions instead of rediscovering them three sessions later.

It also makes the contract itself reviewable. That is easy to overlook. A clean CC is not just better writing; it is risk reduction.

Without structure, AI-assisted development can feel like accelerating into fog.

With lightweight specs, it feels more like driving with a map. You may still take wrong turns, but at least you know which road you meant to be on.

Closing thought

Vibe coding done right is not about making solo projects more bureaucratic. It is about making them less fragile.

The loop gives the work a rhythm:

Think clearly. Write the contract. Review the contract. Build narrowly. Test manually. Review honestly. Document what changed. Repeat.

That rhythm keeps the human in charge without wasting the AI’s strengths.

The coding agent can move fast. The docs can remember. The CC can define the box. The assistant can help you learn why the box should look that way. The review can catch ambiguity before it becomes code. The FR can protect the project from “almost right.”

And the solo developer can keep building without needing to hold the entire system in their head at once.

That, for me, is the point.

I spent a week trying to make AI-assisted development less chaotic.

davidvk89 — Tue, 30 Jun 2026 12:52:54 +0000

Hi, I’m David.

I’m close enough to middle age that I have no interest in pretending I discovered the future of software development in a week.

What I did do was spend one serious week building a small local app with AI assistance, while trying to keep the project understandable.

That turned out to be harder, and more interesting, than I expected.

The coding agent could move quickly. Sometimes very quickly. It could generate code, refactor, write boilerplate, and help move the project forward.

But it could also widen scope, preserve the wrong assumption, “helpfully” redesign something I wanted to keep boring, or act on context that was never meant to become implementation work.

The main lesson I took from that week was simple:

AI-assisted development is not only a coding problem.

It is a context management problem.

So I started using a lightweight loop:

Task Brief      -> think through the problem
Codex Contract  -> give the coding agent a bounded instruction set
Final Review    -> test, inspect, patch, and update project memory

The result was not perfect AI coding.

The result was reviewable AI coding.

That distinction felt important enough to write down.

The three articles

I published three companion articles from that first week.

They are meant to stand on their own, but together they describe the workflow, the memory system, and the objections I think are worth taking seriously.

1. Vibe Coding Done Right

This is the accessible starting point.

It explains how I used a lightweight, spec-driven workflow as a solo developer working with ChatGPT, Codex, VS Code, PowerShell, and a local LLM through LM Studio.

The point is not the exact stack.

The point is the separation:

one place for thinking, learning, and review;
another place for bounded implementation;
documentation as the memory that keeps the next task grounded.

davidvk89

Jun 30

Vibe Coding Done Right

#ai #webdev #programming #productivity

12 min read

2. Documentation as Project Memory in AI-Assisted Development

This is the more technical case-study piece.

The part that surprised me most was documentation.

Not documentation as a polished manual.
Not documentation as a chore at the end.
Not documentation nobody reads.

Documentation as project memory.

The project used a small set of live documents to preserve architecture, data shapes, API contracts, and technical debt.

Those documents were updated as part of the implementation transaction, not someday after the work.

That gave the next AI-assisted task a cleaner starting point.

davidvk89

Jun 30

Documentation as Project Memory in AI-Assisted Development

#ai #webdev #programming #productivity

7 min read

3. Defensive AI Engineering: Hardening the Project Memory Loop

This one is for the reasonable skeptics.

Because the obvious criticisms are fair.

Isn’t this just documentation debt?

Why manually pass context around when IDE agents can read the repo?

Can you trust AI to update its own docs?

Does this scale beyond one solo developer building a prototype?

I do not think those questions should be hand-waved away.

The third article is my attempt to stress-test the workflow rather than sell it as a universal answer.

davidvk89

Jun 30

Defensive AI Engineering

#ai #webdev #programming #productivity

5 min read

Supporting repo

I also published a small GitHub repo with the supporting files from the case study.

It is not a framework or package.

It is just the artifact trail: project-memory files, example Codex Contracts, and supporting notes from the development sequence.

davidvk89 / ai-project-memory-loop

A lightweight workflow for using live project documentation as memory in AI-assisted development.

ai-project-memory-loop

Supporting files for a one-week case study in using live project documentation as memory during AI-assisted development.

Core idea

AI-assisted development has a context problem.

The workflow documented here uses a lightweight loop:

Task Brief      -> explore the problem
Codex Contract  -> define the bounded implementation
Final Review    -> test, inspect, patch, and update project memory

The project memory files are updated as part of the work, not someday after the work. That gives the…

View on GitHub

Why I’m posting this

I am not claiming authority on AI engineering.

Maybe someone else is also trying to use AI coding tools without turning their project into a mysterious pile of files that technically runs but no longer makes sense.

If so, I hope some part of this is useful.

A few moments later...

I spent another week trying to understand why it worked

After publishing the first three articles, I kept digging into what had actually made the workflow useful.

The original series explains the practical project: how I tried to make AI-assisted development less chaotic during one week of building. The follow-up article is different. It is a deeper thought trail about the mechanism the prototype exposed.

That mechanism is not just “better prompting” or “better documentation.” It is documentation functioning as operational project memory, maintained through controlled context flow.

The follow-up also explains the harder boundary: if documentation can become project memory for AI-assisted work, then documentation becomes part of the instruction surface future agents may rely on. That makes review, implementation authority, trust gates, and security boundaries part of the story.

Case File: Context Drift

A Thought Trail on Operational Memory, Controlled Context Flow, and AI-Assisted Development

davidvk89

Jul 2

Case File: Context Drift

#ai #softwareengineering #programming #documentation

10 min read

Meanwhile...

I Just Wanted Bannerlord NPCs to Remember Things

The practical series explains what I built.

The deep dive explains the mechanism I later found inside the workflow.

But the actual origin was much less grand: I was playing Bannerlord with an LLM, got hooked on the prose, and then realized the world needed memory if the magic was going to survive more than a few sessions.

That path led to character memory, context packets, trust gates, and eventually the same controlled-context problem showing up in the development workflow itself.

davidvk89

Jul 2

I Just Wanted Bannerlord NPCs to Remember Things

#ai #gamedev #devjournal #programming

5 min read