Reference Codes for Better AI Decisions

This is part two of AI Working Agreements. The series begins with AGENTS.md Is a Communication Protocol, an overview of the working agreement I use with AI coding agents.

The highest-leverage rule in my AGENTS.md file is not about code. It is a convention for naming parts of a conversation.

When an agent presents several options, decisions, questions, risks, or recommendations, it gives each item a short reference code. Those codes remain stable while we discuss the work.

1O1  Keep authentication inside the application
2O2  Move authentication behind an identity proxy
3O3  Adopt a managed authentication service
4
5K1  Migration could invalidate existing sessions
6K2  The managed service adds a runtime dependency

I can respond with:

1Take O3. K2 is acceptable. How would you mitigate K1?

That small protocol makes long technical decisions faster and less ambiguous.

The problem is addressability

AI conversations accumulate context quickly. An architecture discussion can contain three approaches, four risks, two open questions, and a revised recommendation in a few messages.

Without stable names, we refer to those ideas indirectly:

• "the first option"
• "the part about deployment"
• "the earlier concern"
• a pasted paragraph from several messages ago

Those references are fragile. "The first option" may stop being first when a new option is inserted. A paraphrase can change the meaning of a risk. Repeating a paragraph adds more text without making its identity clearer.

Reference codes give an idea an address.

The useful property is not brevity. It is persistence. O3 means the same option after we compare it, modify it, reject it, and return to it later.

Use a small semantic vocabulary

My common prefixes are:

• O — option
• D — decision
• Q — question
• R — recommendation
• K — risk
• A — action

The prefix tells us what kind of object we are discussing. The number distinguishes it from others of the same kind.

There is no universal alphabet. A security team might use T for threat and M for mitigation. A product team might use H for hypothesis and E for experiment. The notation should reflect the decisions the team actually makes.

What matters is that codes do not collide inside the same discussion. Using R for both risks and recommendations looks compact until both appear together. Distinct prefixes preserve the clarity the system is supposed to create.

Apply the threshold deliberately

I do not want every sentence to look like an issue tracker.

The working agreement asks for codes when there are three or more related items. One or two simple questions can remain normal prose. A complex answer with several categories benefits from structure.

That threshold is not mathematical. It is a guard against two failure modes:

1. Too little structure makes long discussions hard to reference.
2. Too much structure turns ordinary communication into ceremony.

A useful test is whether I am likely to refer to an item again. If the answer is yes, a stable code is probably worthwhile.

Preserve codes instead of renumbering

Once assigned, a reference should not change.

Suppose we begin with three deployment options:

1O1  Manual release
2O2  Merge-triggered deployment
3O3  Scheduled deployment

If we later reject O1, the remaining options should stay O2 and O3. Renumbering them makes earlier messages incorrect.

A new alternative becomes O4. A meaningful variation can become O2a if it is truly a branch of O2, although I prefer a new number when the variation has different risks or ownership.

Decisions should get their own code rather than silently changing an option's meaning:

1D1  Use merge-triggered deployment with production approval

O2 remains the option we evaluated. D1 records what we chose.

This distinction becomes valuable when reviewing why a decision was made. Options describe the decision space. Decisions describe commitment.

References make combination easier

Many technical choices are not a vote for one complete package. The useful answer often combines parts from several proposals.

1O1  Centralize validation in CI
2O2  Run all validation locally before review
3O3  Let each package define its own checks
4
5R1  Use O1 for enforcement and O3 for package ownership.
6R2  Keep a small local check set from O2 for fast feedback.

I can accept R1, modify R2, and reject the premise that every CI check must run locally. We can work at the level of ideas instead of rewriting a merged proposal after every response.

Codes also improve disagreement:

1I agree with D1, but the evidence for K3 is weak. Verify K3 before we act on A2.

The sentence separates agreement, uncertainty, and sequence without restating any of their full descriptions.

A complete decision example

Consider a team deciding how an AI agent should handle dependency upgrades.

The agent begins with options:

1O1  Upgrade dependencies whenever a task touches them
2O2  Upgrade only when the user asks
3O3  Allow patch upgrades autonomously and ask for minor or major upgrades

It identifies risks:

1K1  Unrelated upgrades increase review scope
2K2  Patch releases can still contain regressions
3K3  Delayed upgrades increase security and migration cost

It asks questions:

1Q1  Does CI include integration coverage for dependency behavior?
2Q2  Are lockfile-only changes reviewed differently?

After answering the questions, we record a decision:

1D1  Use O3 for development dependencies with passing validation.
2D2  Use O2 for production dependencies and anything with a migration guide.
3A1  Document the distinction in AGENTS.md.

The final record is compact, but it still points back to the full reasoning. If D1 causes problems later, we can identify which assumptions and risks were part of the choice.

Keep codes stable across summaries

Long agent sessions are often summarized or compacted. Reference codes should survive that process.

A useful summary does not say:

1The team discussed several deployment approaches and chose the second one.

It says:

1D1 selected O2: merge-triggered deployment with production approval.
2K1 remains open: rollback ownership is not documented.

The references preserve continuity between the detailed discussion and the compressed state. They also make it easier to resume the decision in a later session.

For durable work, I may carry the decisions into an issue, architecture note, or pull request. The codes can remain while the work is active, but they are coordination metadata. Customer-facing copy and polished documentation should normally use natural language instead.

Common failure modes

Coding everything

If every bullet gets a label, the labels stop signaling importance. Use them where continued reference is likely.

Reusing a code

A code should identify one idea inside a discussion. If R2 changes meaning, create a new recommendation and mark the old one as superseded.

Renumbering after deletion

Do not close gaps. Historical stability is more valuable than a tidy sequence.

Mixing categories

If R1 means "risk" in one section and "recommendation" in another, a sentence such as "accept R1" becomes unclear. Use distinct prefixes.

Exporting internal notation blindly

Reference codes are excellent inside a working conversation. They can feel cryptic in an email, article, customer message, or release note. Remove them when the audience did not participate in the protocol.

Treating codes as reasoning

A label does not make an option complete or a risk credible. The full item still needs evidence, tradeoffs, and consequences. The code only gives that work a stable handle.

Add the rule to AGENTS.md

A compact instruction is enough:

1## Reference points
2
3- When presenting three or more options, decisions, questions, risks,
4  recommendations, or actions, assign each a short code.
5- Use stable semantic prefixes such as O1, D1, Q1, K1, R1, and A1.
6- Preserve those codes throughout the conversation and in summaries.
7- Do not add codes to short answers or final copy intended for an outside audience.

Adjust the vocabulary to your own work. The system fails if the notation is harder to remember than the ideas it names.

The larger lesson is that productive AI collaboration does not only depend on better answers. It depends on making the parts of those answers easy to address, preserve, and revise together.

Resources

• AGENTS.md — the open instruction-file format and examples
• Architecture Decision Records — a durable approach to recording architectural decisions and consequences
• Markdown Guide — syntax for portable working agreements and decision notes