AI Dictionary: Design and Project Guidance

This dictionary focuses on LLM-based coding agents. Product behavior varies by model, API, and harness. Entries explicitly marked as informal describe working vocabulary used here, rather than universal technical definitions.

Dictionary overview

Design concept

The working understanding of what is being built and why: goals, behavior, constraints, and tradeoffs. In collaborative agent work, the aim is to make that understanding shared. This entry uses the phrase as a practical design term, rather than a formal AI mechanism.

A spec, prototype, and implementation each represent parts of the concept; none guarantees shared understanding. An agent can implement a literal request while missing the intended outcome, and unclear requirements are only one possible cause of a wrong result.

For example, “add search” may mean title matching to the agent and full-text matching to the author. Agree on concrete queries and expected results before deciding the design is settled.

Check understanding through examples, constraints, and acceptance criteria. Anticipating your preferences can be useful, but agreement alone may be sycophancy. Revise the documents when the design changes.

Grilling

An informal name here for a focused discovery interview: the agent surfaces unresolved decisions and asks the user to resolve them. It can propose options and a recommendation when evidence supports one.

For example, before specifying search, the agent asks whether it should match titles only or full article text, explains the tradeoff, and records the author’s choice. Dependent questions follow after that choice.

Ask about judgments the author owns; investigate facts the agent can verify. One question at a time can help with dependencies, while a small batch can suit independent choices. Draft notes can capture uncertainty during the interview; the important rule is not to present unresolved guesses as approved requirements.

When a decision depends on seeing the behavior, build a prototype and return to the interview with something concrete to assess.

Prototyping

Having the agent build a quick, rough version of something, for when conversation is too low-fidelity and you need a real artifact to talk about.

Grilling resolves design decisions in conversation. Conversation is cheap, but it’s low-fidelity: some questions can’t be answered in words — how an interaction feels, whether an API shape is ergonomic in real calling code, whether the layout works at real data sizes. The interview hits a question and your honest answer is “I don’t know, I’d have to see it.” Past that point the discussion circles. Instead, have the agent build the thing, look at it, and come back to the conversation with an answer.

Agents lower the cost of building, which is what makes this practical. Some rough versions become much cheaper to build with agents, making more experiments practical; the savings depend on the task and verification needed. It’s a human-in-the-loop technique: the prototype is there for you to react to.

You usually don’t stop at one look. Iterate with the prototype — react, ask for a change, react again — so each round resolves another decision against the real artifact, at a higher fidelity than conversation allows.

A prototype doesn’t have to be all-scrappy. You can build the pieces you’re actually evaluating to production quality, so when the decision lands, the component or API you reacted to can transfer into the real codebase. Reference useful prototype findings in the spec, and review any reused code for production requirements.

For example, build a disposable search-results page with realistic long titles to decide whether the layout works. Record that decision before turning the prototype into a production feature.

Spec

A specification states intended behavior, scope, constraints, and acceptance criteria. It can cover a tiny change or a project spanning many sessions. Tickets may implement it, but are not a required part of its definition.

For example: “Empty search input shows all published posts; matching is case-insensitive; drafts never appear.” That specifies observable outcomes without choosing how the search code is written.

A PRD often emphasizes user outcomes; a technical design or RFC often explains interfaces and implementation choices. An execution plan tracks work and dependencies. These documents can be combined for small work, but their purposes differ.

For agent work, a spec is also a durable context source. Update it when an approved requirement changes, and distinguish decisions from assumptions so a fresh session does not mistake a guess for an agreement.

Ticket

A bounded unit of work, often an issue in a tracker. It names an outcome, acceptance criteria, and relevant context. A ticket may stand alone or implement part of a spec, and may span more than one agent session.

For example: “Add the empty-search state; cover empty and whitespace-only input; use the existing search component; depends on the search API ticket.” That gives a fresh worker scope and a completion test.

Sizing tickets to one focused session can be a useful agent-work practice, rather than a defining rule. Split work when scope or verification becomes difficult to manage, not solely at an assumed token threshold.

Dependencies determine which tickets are ready. Independent ready tickets can run concurrently, provided shared files, integration steps, and review ownership are coordinated.

AGENTS.md

A project instruction file that supporting harnesses discover and load — the project’s standing brief to the agent. Loading rules, directory scope, precedence, and size limits vary. Cross-harness convention; some harnesses also have their own variant (Claude Code’s is CLAUDE.md).

Because it loads automatically, it’s one way to avoid repeating yourself across sessions. A correction given in one session may be unavailable in the next unless history or memory carries it forward, leaving you to tell fresh sessions that the project uses pnpm, that tests run with a particular flag, that a directory is generated and shouldn’t be touched. When you’ve corrected the agent for the same thing twice, that correction is a candidate line for AGENTS.md.

Suitable content includes information the agent cannot reliably derive from the code: build and test commands, conventions the codebase doesn’t make obvious, hard constraints (“never edit the generated client”). Short and declarative — it’s a brief, not documentation.

The trade-off is that applicable contents can be loaded repeatedly, subject to the harness’s discovery and truncation rules. Instructions accumulate, most of them irrelevant to any given task, and a long AGENTS.md costs tokens and can make relevant rules harder to find. Length alone does not determine adherence; clarity, scope, and conflicting instructions matter too.

For example, put “Run npm run test:unit for unit tests” in the project brief and link specialized deployment steps separately. Codex’s AGENTS.md guide documents one discovery and precedence scheme. These are model instructions, not a security boundary.

Progressive disclosure

Loading only the context an agent needs right now, with context pointers to the rest. Borrowed from UI design, where it means showing users only the controls relevant to their current task and hiding the rest behind a click.

The technique exists because context is a cost twice over. Loaded material occupies active context and can add processing cost on requests that include it, even if cached-input rates apply. An AGENTS.md stuffed with the full style guide, deployment runbook, and database conventions can obscure the relevant guidance — irrelevant instructions can distract from the current task. If the agent misses a loaded rule, investigate its clarity, priority, and placement as well as context size.

Progressive disclosure inverts this. Keep the always-loaded layer small — a sentence per topic and a pointer to where the detail lives. The agent reads the style guide when it’s writing a component, the deployment runbook when it’s deploying, and neither when it’s fixing a test. Skills are the pattern built into the harness: a short description loaded every session, the full instructions only when triggered.

Context pointer

A mention in one document that points to another, so the agent can pull it into the context window only when the task calls for it. The unit progressive disclosure is built from.

The reason to use a pointer (instead of inlining the content) is cost. A pointer is one line in the context window. The document behind it might be thousands of tokens, but its full contents need not occupy context until retrieved. Inline a 2,000-token runbook in AGENTS.md and each session that loads it uses that context capacity; replace it with “deploy process: see internal/deploy.md” and sessions can retrieve it when relevant. The agent follows the pointer with a tool call when the task matches.

A pointer needs two parts to work: a stable path, and enough description for the agent to know when following it is worth it. A bare path can be harder to select correctly; “see internal/deploy.md” with no hint of what’s inside can be overlooked by a session that needs it. Write the line so it matches how tasks present: “release, deploy, or rollback — read internal/deploy.md first”.

Pointers are everywhere once you look: lines in AGENTS.md, skill descriptions (the harness loads the description; the skill body waits behind it), filenames in a directory listing, links between docs.

A pointer can also tie a secondary source back to the primary source it was derived from — the compaction summary that names the original transcript, the doc that names the source file it describes. This makes the secondary source’s lossiness recoverable: when the summary turns out not to be enough, the agent follows the pointer and reads the original, instead of working from whatever the summary kept.

Skill

A teachable capability bundled as a unit — instructions and resources for doing one task well, kept in the environment until a context pointer pulls it into the context window for the task at hand. The unit of progressive disclosure in a harness.

Skills are an open standard, defined at agentskills.io — originally developed by Anthropic. Supporting harnesses can read the common format, though discovery, permissions, tools, and runtime dependencies can limit portability. The format is a folder containing:

• A SKILL.md file — metadata (a name and description, at minimum) plus the instructions themselves
• Optionally, scripts the agent can run
• Optionally, templates and reference material the instructions point to

In a harness using progressive discovery, the name and description are available first, and the body is loaded when selected or explicitly invoked. Until then, the skill takes up almost no room — a sentence or two of tokens, however large its full instructions are.

This distinguishes task-specific skills from standing project guidance such as the applicable AGENTS.md files. A skill is read when a particular kind of work comes up — releasing, scaffolding a new service, writing a migration — and can remain unloaded otherwise. A skill is guidance and resources, not executable enforcement; scripts still depend on available tools and permissions.

DX

Developer experience — how easy a codebase and its toolchain make it for humans to do good work. Good DX is fast feedback, clear error messages, documentation that answers the question you actually have, and setup that works on the first try. The term long predates AI coding; it contrasts AX.

DX covers the human developer’s interaction with tools, code, processes, and collaborators. One difference from agent experience is how project knowledge persists between tasks. A human can retain familiarity with a codebase across working days, which is why poor DX is survivable: they route around slow CI by batching their pushes, around missing docs by asking in Slack once, around confusing structure by remembering where things live. The workarounds accumulate, and a team ends up productive in a codebase that fights them.

An agent without persistent history or memory may need to rediscover project knowledge each session — it benefits from the fast test suite and the clear error messages, but anything it figured out yesterday is unavailable unless history or persistent memory supplies it again, through the harness’s supported interfaces. That’s the gap AX names: the parts of DX that survive when the developer is an agent, plus concerns humans don’t have, like keeping the context window free.

The overlap means DX investment often improves AX for free — strict types, fast tests, and predictable structure help both. The divergence means it doesn’t always: a beautiful onboarding doc helps a human for a week and can help an agent when it is discoverable through project guidance, search, or another context pointer.

For example, a one-command setup and an error that names the missing configuration improve a human developer’s experience without requiring remembered workarounds.

AX

Agent experience — how well the environment is set up for an agent to do good work in a codebase. The agent-facing counterpart to DX. When the same agent performs well in one repo and badly in another — same model, same harness — the environment is one important variable to investigate. Clear project guidance, usable tools, and fast feedback can improve results without changing the model.

This dictionary uses AX to mean agent experience; the acronym has other meanings elsewhere. Three useful dimensions are:

Dimension	What good AX looks like
Automated checks	Fast, deterministic automated checks — types, tests, lints — that the agent can self-correct from without a human
Architecture	A codebase the agent can navigate without reading everything: predictable structure, a lot of behavior behind small interfaces, names that say what things do
Free context	AGENTS.md, skills, and tools kept lean, so active context has room for relevant evidence and instructions

AX and DX overlap — good checks and clean architecture help both audiences — but they diverge. Humans can use accumulated knowledge and colleague conversations to bridge missing documentation. Agents need that information supplied through an available interface; the same gaps can hurt both audiences. Text-based agents benefit from structured failure output; agents with browser or computer-use tools may also inspect visual interfaces. A codebase can have good DX and poor AX.

For example, a test command listed in project guidance, with a failure that names the assertion and file, gives the agent a direct path from failure to investigation.