مقتطف من الدرس

Repository Map for AI Coding Agents: Project Structure and State Without Memory

How to give an AI coding agent a repository map when it has no memory between sessions: what to measure, four principles of a good map, project file structure and ACID-style guarantees for agent state.

the repository as the single source of truth the repository map ACID for agent state

ما ستتعلمه في هذا الدرس

You will be able to audit your repository for blind spots that leave the agent guessing.
You will organise your file structure so the agent reads rather than guesses.
You will apply ACID principles to how the agent records its progress and decisions.

بداية الدرس

📖 The agent reinvents the architecture from scratch — and here's why

Architectural decisions live in Confluence, Slack, Jira and in the heads of two senior engineers
For humans this works — you can just ask
An agent can't ask
Every new session is a fresh guess at the project structure

Some of your team's architectural decisions live in Confluence — and half of those are already out of date. Some live in Slack, where nothing can ever be found again. Some sit in Jira, stripped of their context. And the rest live in the heads of two senior engineers. For humans this somehow works: you can wander over and ask. An agent can't ask. It has no memory between sessions and no access to anyone's head. So every time it opens the project afresh, it honestly invents the structure from scratch — and loses track of what lives where, even though, on paper, all the information exists somewhere.

Three sources in total — beyond them, the agent knows nothing

The system prompt and the task description
The contents of the repository files
Tool output
There are no other inputs

An agent has exactly three sources of information: the system prompt along with the task description, the contents of the repository files, and the output of whatever tools it calls. This isn't an exaggeration or a metaphor — it's a literal description of its sensory apparatus. Any knowledge that isn't in one of those three places simply doesn't exist for the agent. It can't ring a colleague, flick through a wiki in a browser, or remember yesterday's chat — none of that is available to it.

The OpenAI principle: the repository is the specification

The repository is the authoritative source on decisions
On constraints and the current state
On verification standards
Neither Slack nor Confluence gets a say

OpenAI put this bluntly: the repository is the specification. Not a supplement to the specification, not an illustration of it — the authoritative source itself, for decisions, constraints, the current state of the project and verification standards. In this model, Slack and Confluence simply get no say: if a decision lives only there, it doesn't exist for the agent. That changes where you put important things — not wherever happens to be convenient to write, but wherever the agent will actually read.

الدرس الكامل متاح بالاشتراك

و20 شريحة أخرى في النسخة الكاملة.

تُفتح الفيديو وجميع الشرائح والملاحظات والاختبارات والمرشد الذكي والمقابلة بعد تسجيل الدخول والاشتراك.

تسجيل الدخول أو إنشاء حساب الاشتراك الآن

محتوى الدرس

📖 The agent reinvents the architecture from scratch — and here's why
Three sources in total — beyond them, the agent knows nothing
The OpenAI principle: the repository is the specification
🤔 Myth: if it's in the repository, the agent will see it
What to measure: knowledge visibility gap
What to measure: knowledge decay rate
❓ Stop-check: how many questions can the agent answer?
Principle 1: knowledge lives next to the code
Principle 2: one standard entry point
Principle 3: minimal, but complete
Principle 4: updated alongside the code
💡 Debrief: four principles close the gap
A working repository structure for your agent
Top level: entry point, progress, decisions
The service layer: .agent/ and scripts/
Pitfalls: documentation that lies
ACID for agent state
Consistency: a green check after every step
Consistency: a green check after every step
Isolation: two transfers from one account don't clash
Durability: context doesn't count
Homework: close your knowledge gap
The repository as a contract, not an archive