Making Information Usable by AI Agents

An agent updating this tutorial needs more than access to its files. It needs to know where the chapters live, which terms we use, and which decisions its changes must respect.

An AI agent combines a language model with tools for operations such as reading files, editing sources, and running checks. A chat prompt describes the task; repository access comes from the configured tools and permissions. The sources and processing rules from earlier chapters provide useful context; the actual repository adds the conventions and rationale needed to work on the project.

Start with an entry point, not a giant prompt

This repository has an actual AGENTS.md file. It tells working agents where the maintained chapters live, which paths Astro reads, how chapter IDs are preserved, what related information may need checking, and which commands verify changes.

AGENTS.md is a working-instructions entry point. It should stay concise and lead to the maintained knowledge needed for the task. Different agent products have different instructions and file-discovery conventions; simply placing a file in a repository does not guarantee that every agent reads it.

What knowledge should a project maintain?

The source map describes what exists. A decision record explains why a choice was made, such as keeping the core tutorial browser-first. Agent instructions point to both. This repository’s decision register records the supplied direction on 19 October 2026, not a reconstructed history of earlier approvals.

flowchart TB
 accTitle: Project knowledge map
 accDescr: Working instructions link to architecture, terminology, decisions, and maintained sources. Checks and review assess the result.
 A[AGENTS.md: working instructions] --> P[Project architecture and source map]
 A --> G[Glossary and writing conventions]
 A --> D[Decision records and rationale]
 P --> S[Maintained sources, relationships and schemas]
 G --> S
 D --> S
 S --> V[Checks and source-grounded review]

Source note: The diagram maps routes through project knowledge. Linked files are read when needed; they are not automatically loaded into a model.

Keep source authority and permissions clear

For a chapter update, the agent should read the current source and applicable conventions, then report the files it changed and the checks it ran. Diffs, validation results, and generated pages give reviewers evidence for assessing the result; a passing build alone does not approve its meaning.

Source selection matters too: a proposed requirement cannot support a claim that a feature is implemented. Confidential material must stay within its permitted environment. AGENTS.md guides the work but grants no permissions to read, share, or publish information.

Explore: Where should a project rule live?

Where would you maintain a stable-identifier rule and the explanation of why it exists?

Explore further: The agent context and project-knowledge guide examines this repository’s guidance, source selection, decision records, permissions and verification in greater detail. No AI account is needed to read it; its optional local examples require suitable tooling.

Organizing project knowledge helps agents find and interpret the material they need. People benefit from that organization too. Chapter 9 uses a fictional customer-and-contract example to show how readers can follow relationships and ask their own questions.