Chapter C52 · Interactive Course
Which instruction file does what?
READMEs, agent guidance, scope, saved notes and what enforces nothing.
Core Learning Concept
Sort workspace configuration files by purpose, discovery rules, and authority. Distinguish project introductions, active agent guidance, saved historical notes, and access boundaries using the host's clearly documented discovery order and precedence rules.
What You’ll Learn in This Chapter
-
README.md introduces a project
Identify human-oriented project information.
A README commonly introduces a project, its setup, and how to work with it. Humans and agents may both read it. Its existence does not guarantee automatic loading or special instruction priority. Use it for orientation, then identify any additional guidance and configuration the current host actually recognizes.
-
AGENTS.md gives project guidance
Explain a convention for instructions to compatible agents.
AGENTS.md is a convention some coding-agent hosts use for project guidance. It can describe commands, architecture, and local constraints. Discovery, scope, and precedence depend on the host. Write specific, current instructions and verify that the relevant file is loaded for the workspace being used.
-
CLAUDE.md is a product convention
Recognize Claude Code guidance separately from generic Markdown.
CLAUDE.md is a project-guidance convention associated with Claude Code. Other hosts may use different names and discovery rules. Similar Markdown syntax does not make those conventions interchangeable. When sharing guidance across products, verify supported imports or references and maintain consistency rather than assuming a filename works everywhere.
-
Scope determines where guidance applies
Resolve a supplied root-versus-folder instruction chain.
Scope determines which files or tasks a guidance rule applies to. A repository-wide instruction may coexist with a more specific directory instruction. Hosts differ in how they discover and combine them. Follow the documented order for the current product and inspect the actual applicable files when behavior is surprising.
-
Memory notes can become stale
Separate a saved observation from current evidence.
A memory note records information for possible reuse, often from earlier work. It may become outdated as code, services, or decisions change. Treat it as a lead to relevant evidence rather than automatic proof of current state. Verify drift-prone facts before acting and update notes only through the permitted process.
-
Persona files shape behavior cues
Explain SOUL.md-like conventions without personifying software.
A persona or behavior file supplies cues such as tone and working preferences if the host loads it. It can influence responses without changing model parameters. Its presence on disk does not prove it is used, and its tone does not establish human experience or awareness inside the system.
-
Instructions are not access enforcement
Separate written rules from operating permissions.
Instructions describe how an agent should behave; access controls constrain what operations are permitted. Both are useful and serve different purposes. A sentence saying “do not edit outside this folder” is not equivalent to an enforced filesystem boundary. Inspect the actual configuration when the distinction matters.
-
Sort the workspace notes
Place an overview, agent convention, skill entrypoint, saved fact and access setting into their roles, and explain which host consumes each.