AI coding agents can make a new workspace feel deceptively easy.

You open a fresh repository, write a few sentences, attach a file or two, and within minutes the agent is ready to generate code. It feels fast. It feels impressive. It also feels like progress.

Sometimes it is.

Sometimes it is just very fast confusion.

That is the part I think people underestimate.

The problem is usually not that the coding agent is weak. The problem is that the repository is empty of working memory. The product rules are still floating around in your head. The business logic is scattered across old chats. Scope decisions live in yesterday’s conversation. Important constraints exist, but not in any durable place the agent can reliably use.

So the agent starts building anyway.

And that is where trouble starts.

Most developers do not enjoy writing documentation. I do not either. But when I work with AI coding agents, I treat documentation differently now. I am not writing it mainly for myself to read later. I am writing it so the agent can work properly inside the project.

That is why I do not start a new workspace by asking Codex to write code.

I start by giving the repository a memory.

For me, that usually means two things:

• an artifacts/ directory
• an AGENTS.md file

Those two things do a lot more work than they look like they do.

The problem is not only coding. It is continuity.

One of the easiest mistakes in AI-assisted development is assuming that the agent will somehow “understand the project” after a few good chats.

It will understand the current conversation, maybe quite well.

That is not the same thing.

A real product is not a single prompt. It is a live thing. It keeps changing. Features get added. Earlier decisions create constraints. Business rules pile up quietly in the background. The first version makes tradeoffs. Later improvements depend on those tradeoffs. Edge cases appear. Security rules get added. Non-goals matter just as much as goals.

You cannot keep carrying all of that in your own head and re-explaining it every time.

At some point, the conversation starts sounding ridiculous.

You are effectively saying: I need to add feature C, which is an extension of feature A, which already behaves in these ways, and it also touches feature B, which follows those rules, and do not forget that this old business rule still applies, and also do not break the thing we decided three weeks ago.

That is not a serious long-term workflow.

The repository needs to remember things so I do not have to keep reconstructing the project from memory every time I open a new chat.

artifacts/ is where the repository remembers

This is why I create an artifacts/ directory early.

The point is not folder beauty. The point is memory.

I want a place where the project can store the documents that define how it should behave. Not vague notes. Real source-of-truth material.

That usually includes things like:

• product requirements
• business rules
• feature documentation
• API contracts
• design rules
• release notes
• implementation constraints
• decisions about scope and non-goals

The exact structure changes depending on the repository, but the principle stays the same: if the code must respect something, that thing should live somewhere durable.

So instead of hoping I remember every rule about feature A and feature B, I let the documentation remember it.

Maybe I have:

• artifacts/business-rules/feature-a.md
• artifacts/business-rules/feature-b.md
• artifacts/api/token-flow.md
• artifacts/design/admin-ui-rules.md
• artifacts/release-notes/

Now the project has a memory system.

And this matters more than many younger developers realize.

The whole idea of a source of truth is still not deeply built into how a lot of developers think, especially in our region. Many people still work as if the real product knowledge lives in scattered chats, half-memory, old messages, and whoever happens to still remember why a decision was made.

That may work for a while with small teams and simple projects.

It does not work well when you are using an AI coding agent that can produce output very quickly and still be missing half the rules that matter.

AGENTS.md is the operating manual

If artifacts/ is where the repository remembers, AGENTS.md is how the repository teaches the agent to behave.

This file is not a random set of notes. It is the operating manual for the workspace.

It tells the agent things like:

• what this repository actually is
• what the product is trying to do
• what is in scope
• what is explicitly out of scope
• where the source-of-truth documents live
• what to read before implementing
• how to work in stages
• when to stop and ask questions
• when documentation must be updated
• what “done” means in this repo

That matters because a coding agent does not just need context. It also needs guardrails.

I do not want it jumping into implementation because the prompt sounded enthusiastic.

I want it to understand the workflow first.

In my setup, AGENTS.md usually bakes in a few recurring rules:

• read first
• reach high confidence before implementation
• ask focused questions if confidence is not high enough
• do not write code until there is explicit approval
• treat certain docs inside artifacts/ as canonical
• update those docs when behavior changes
• keep changes scoped to the approved stage

That is not bureaucracy for the sake of it.

That is how I reduce rework, drift, and fake progress.

I am not writing documentation for fun. I am reducing agent memory burden.

This is the part I think many people misunderstand.

When I talk about artifacts/ and AGENTS.md, some people hear “documentation process” and immediately imagine overhead.

I get it. Most developers do not enjoy writing documentation. I do not either.

But in this workflow, the documentation is doing a different job.

It is not there because I suddenly became emotionally attached to markdown.

It is there because the agent needs governed context.

The repository should not depend on my ability to remember every business rule, every scope boundary, every earlier decision, and every exception that accumulated across the product.

That is too fragile.

I want the codebase to be surrounded by enough structure that the agent can work with continuity instead of constantly depending on conversational reminders.

In other words, I am not trying to become more formal.

I am trying to become less forgetful at the system level.

The nice part: I do not write most of this manually anymore

There is also a practical point here that makes this much less painful than it sounds.

At this point, creating AGENTS.md is barely a task I think about.

I do not sit there writing it from scratch like it is a literary project.

My usual setup is simple:

1. I place the PRD or product brief inside artifacts/
2. I attach a few AGENTS.md files from other workspaces
3. I open the first chat in the new Codex workspace and ask it to create a new AGENTS.md for this project by extracting my working methodology from the previous ones and adapting it to the new product context

That is usually enough.

In less than a minute, I have a solid first draft of a new AGENTS.md.

Then I review it, adjust anything that is specific to that repository, and move on.

So no, I am not manually rebuilding the whole operating system every time.

The first time requires thought. After that, the method starts reproducing itself.

That is one of the practical advantages of having a clear methodology. Once it exists, your future workspaces get easier to set up.

The setup changes from one repository to another

This part matters a lot.

I am not using one generic AGENTS.md for everything and pretending all projects have the same needs.

They do not.

A public WordPress plugin does not need the same rules as a private broker plugin.

A mobile app does not need the same workflow notes as an n8n automation repo.

A data-heavy system does not need the same constraints as a content-focused site.

The structure is similar, but the actual instructions must adapt to the repository.

For one project, the important sections may focus on plugin scope, localization rules, shared hosting limitations, and release notes.

For another, the important sections may focus on API authorization, mobile UI rules, or migration architecture.

That is exactly why I like this method.

It is standardized without becoming generic.

The repo gets a familiar operating model, but the actual rules still reflect the real product.

What I usually put inside artifacts/

I try to keep this practical.

I am not trying to create a corporate document cemetery.

I want documents that help the agent make better decisions and preserve continuity.

A simple example might look like this:

artifacts/
├── business-rules/
│   ├── feature-a.md
│   ├── feature-b.md
│   └── retention-policy.md
├── api/
│   ├── auth-flow.md
│   └── webhook-contract.md
├── design/
│   └── admin-ui-rules.md
├── release-notes/
└── prd.md

That is enough to be useful.

The important part is not how impressive the tree looks. The important part is that the project now has durable memory.

What I usually put inside AGENTS.md

I also keep this structured and opinionated.

A simple version usually includes:

• purpose of the repository
• collaboration protocol
• source-of-truth files and folders
• product scope and non-goals
• technical environment baseline
• engineering standards
• implementation workflow
• documentation update rules
• definition of done
• maintenance rule

And yes, I usually include stage gates, confidence thresholds, and explicit approval rules.

Some people may find that strict.

I find it cheaper than cleaning up after a fast misunderstanding.

One important rule: let the agent maintain the memory too

This may be the most useful practical point in the whole method.

I do not want artifacts/ to become a folder that gets outdated the moment real development starts.

So I push one more rule into AGENTS.md:

If a task changes behavior, business rules, API contracts, UX expectations, or implementation constraints, update the relevant document inside artifacts/ as part of the same stage output.

That changes the role of documentation again.

Now the docs are not a side activity I keep postponing.

They become part of the actual workflow.

That is important because I am not trying to personally write and maintain every document by hand. I want the system to help maintain its own memory as the product evolves.

That is the real leverage.

This setup makes AI coding feel much less fragile

The practical payoff is straightforward.

When the repository has memory and operating rules:

• I repeat myself less
• the agent guesses less
• business rules are easier to preserve
• product continuity improves
• new chats are easier to start
• stage outputs become cleaner
• the code is less likely to drift from the real product

Most importantly, I stop treating each coding session like a fresh act of reconstruction.

That is a big shift.

Instead of constantly re-explaining the project, I can point the agent to the repo’s memory and working rules, then focus on the stage in front of me.

That is a much better use of both my time and the tool.

Final thought

I do not prepare a repository this way because I want AI development to feel more formal.

I do it because I want it to feel more reliable.

Before Codex writes code, I want the repository to know what it is, what rules matter, where the truth lives, and how work should happen.

So I give it memory in artifacts/.

And I give it operating rules in AGENTS.md.

After that, the coding agent is no longer walking into an empty room.

It is walking into a workspace that already knows how to think.

Want a sample?

I put together a sample AGENTS.md template based on the structure I usually use when setting up a new Codex workspace.

It includes stage gates, confidence rules, source-of-truth guidance, and the requirement to keep artifacts/ updated as the project evolves.

Download it here: AGENTS-sample-template-by-Hasan-Halabi.md