← back to the section

Out of the box an agent knows the language, the framework, and "best practices in general." About your project it knows nothing: not how to build it, not why the queue runs on PostgreSQL instead of a broker, not that an order must never be paid twice.

Worse, it does not remember the previous conversation. Every session starts from zero — as if a new developer joined the team each morning: technically strong, with no context at all. On day one they break nothing; they simply do things "the industry-average way." A month of such days and your code has drifted apart in style.

Configuring an agent is a way to record what matters once, so that it applies by itself — from session to session, and identically for everyone on the team. It comes in four layers — rules, skills, memory, tools — and one safety frame.

Layer 1: persistent project rules

The most basic piece is a rules file the agent always reads. Different tools use different names and formats; the idea is the same: whatever should apply by default lives in the repository next to the code.

What goes in: how to build, run, and test the project; the team's conventions and style; what must not be done — do not touch these modules, do not rewrite without asking; the key architectural facts.

The point is to move agreements out of people's heads and into the agent's context automatically, without re-explaining them every session.

Layer 2: skills — methodology the agent applies on its own

Methodology has an inconvenient property: it lives in articles and heads, but it applies on every code change. Between "I read how it should be done" and "the repository is written that way" lies a gap, and almost everything falls into it. A person remembers a rule the moment they formulate it; a month later, under deadline pressure, they do not. An agent never remembers it at all.

A skill closes that gap. It is a piece of methodology packaged as a capability: the agent picks it up when it sees the right context and follows it — while writing code, while reviewing a change, while designing a new operation.

The difference from a reference document is not the medium — both are usually markdown — but the audience and the moment it fires. An API style guide in a wiki gets read once during onboarding and forgotten. The same guide as a skill fires while the controller is being written. Knowledge stops being reference material and becomes executable.

Hence a useful practice: keep one piece of knowledge in two forms — an article for the human and a skill for the agent, from a single source. They drift apart quickly, so update them as a pair rather than one at a time.

Layer 3: project memory in the repository

Rules say "how it should be," skills say "how to do it." What remains is what the code does not show: why it was decided this way in the first place.

Persistent project memory is markdown files right in the repository, which the agent reads first in every new session. It lives in git together with the code: the code changes, the memory is updated, and both versions travel in one commit. The agent does not "remember" the previous conversation — it re-reads the current state. That is why memory survives a closed chat, a change of model, and a new person joining.

What belongs there is what is not in the code:

  • Decisions and their reasons. "Idempotency keys are kept with a limited lifetime," "we avoid distributed transactions." Without this the agent reinvents the choice every time — and differently each time.
  • Structure and stack. What services exist, what each is responsible for, which libraries are "ours" on this project.
  • Agreements nothing checks automatically: naming, layer boundaries, what is and is not allowed.
  • A pointer to the source of truth about the domain — so the agent goes and reads the specification instead of guessing.

The key difference from documentation: documentation is written for people and explains the system in general. Memory is written for the agent — it is working context, so that decisions come out in your style rather than the industry average.

Layer 4: tools — the agent's hands

For an agent to work with reality instead of inventing it, it needs tools: code search, database access, the issue tracker, documentation.

Every tool used to be wired up with its own bespoke adapter, and "N agents × M tools" turned into N × M hacks. There is now a single protocol for this — MCP: servers act as adapters to specific systems, and the agent talks to all of them the same way.

The mechanics are simple. A server wraps one world — a filesystem, a database, git, an external API — and exposes the actions that can be performed and the data that can be read. A client lives inside the agent: it connects, asks "what can you do," gets a list with descriptions — and from there the model decides on its own when to use what.

For a product engineer this means context is pulled on demand instead of being poured into the model wholesale: the agent goes to the database for the schema, to git for history, to the tracker for the task wording.

Permission boundaries: where the danger is

Everything above is access, and access has to be bounded. The more autonomous the agent, the more the frame matters.

Least privilege. Read-only or write? One table or the whole database? One directory or the root of the disk? By default, exactly as much as the task requires. A database for analysis is handed to a read-only role, not to a superuser.

Irreversible actions go through a human. A write-capable tool means an agent that can delete data, overwrite a file, or send a production request. Models fail plausibly: they will confidently generate something that does the wrong thing. Destructive actions should be either unavailable, or behind a confirmation, or in a sandbox where a mistake costs nothing.

What can leak. Everything the agent reaches ends up in its context, and from there with the model provider and in logs. Production personal data, secrets, and keys do not belong there. A separate risk is third-party servers in your setup: that is someone else's code running with your permissions, and it deserves the same scrutiny as a production dependency.

Limits. On the number of steps and on cost, so that an autonomous loop does not generate hundreds of expensive calls out of nowhere.

Why this is work, not a one-off setup

The temptation is to configure it once and forget. In practice the configuration lives as part of the project's infrastructure and is maintained like the build or the delivery pipeline. A new convention appears — it goes into the rules. A procedure settles — it becomes a skill. An architectural decision is made — it goes into memory. A new system is connected — a tool appears.

It pays off every session: the agent stops asking questions that have already been answered, and behaves the same way for everyone on the team instead of differently depending on who explained it.

In short

  • An agent does not know your project and does not remember the previous session — configuration moves context out of heads and into the repository.
  • Rules are what always applies: build, conventions, prohibitions, architectural facts.
  • Skills turn methodology into behaviour: they fire at the moment of work rather than sitting in a wiki.
  • Memory holds what the code does not show: decisions and their reasons, agreements, a pointer to the specification.
  • Tools over MCP give the agent hands and pull context on demand instead of loading everything up front.
  • Permission boundaries are mandatory: least privilege, irreversible actions through a human, no production data or secrets in context, limits on steps and cost.
  • Configuration is part of the project's infrastructure, not a one-time action.