{"id": "TTC-112", "slug": "structured-rules-yaml-and-agents-md", "title": "Structured rules, YAML, and AGENTS.md", "level": "practitioner", "summary": "Use AGENTS.md as a readable instruction map and structured YAML for narrow machine-checkable rules; keep authority, scope, defaults, and tests explicit in both.", "learning_outcome": "Write a root instruction map and one validated YAML rule whose scope, authority, rationale, and tests agree.", "explanation": "A root instruction file should tell an agent its mode, applicable sources, approval boundaries, and where to find deeper rules. It is a map, not a copy of every document. YAML is useful when fields such as trigger, action, deny condition, owner, and tests must be parsed consistently. Quote ambiguous scalars, keep schemas small, validate syntax and meaning, and choose fail-closed defaults for authority. Human-readable rationale belongs beside the structured rule. More specific instructions must not silently grant authority forbidden by the root contract. Proposed rules remain inactive until reviewed.", "worked_example": "Fictional case: AGENTS.md says the Orchard Research Apprentice may draft source comparisons but never publish. A YAML rule sets action: draft_comparison, publish: deny, on_conflict: ask_editor, and lists two tests. A nested project may narrow sources but cannot change publish to allow.", "exercise": "Create an AGENTS.md outline with mode, instruction precedence, knowledge paths, action boundaries, and tests. Add one YAML rule for a risky transition. Parse the YAML, test allow and deny cases, and have a human compare its behavior with the prose rationale.", "success_criteria": ["The YAML parses and validates against the declared field schema.", "Prose and structured rule produce the same result for normal, ambiguous, and forbidden cases.", "Nested instructions can narrow behavior but cannot exceed the root authority boundary."], "limitations": ["YAML is a data format, not an enforcement mechanism; the runtime must actually apply validated rules.", "Instruction precedence differs across tools, so portability requires testing in the target environment."], "prerequisites": ["TTC-105", "TTC-111"], "next_lessons": ["TTC-113", "TTC-120"], "copyable_material": "# TTC-112 \u2014 Structured rules, YAML, and AGENTS.md\nObjective: Keep portable human instructions and machine-checkable boundaries aligned.\nProcedure: Use AGENTS.md for mode, precedence, paths, and authority; use small validated YAML records for explicit decisions and tests.\nRequired evidence: Retain schema validation, prose-to-rule review, allow/deny tests, and approval state.\nBoundaries: Structured text does not enforce itself; nested files may narrow but never expand root authority.\nCompletion test: The target agent and an independent parser reach the same bounded result for all test cases.\nReview rule: Treat generated work as a draft until the named human reviewer accepts it.", "sources": [{"title": "YAML Ain't Markup Language (YAML) Version 1.2.2", "publisher": "YAML Language Development Team", "url": "https://yaml.org/spec/1.2.2/"}, {"title": "Custom instructions with AGENTS.md", "publisher": "OpenAI", "url": "https://developers.openai.com/codex/guides/agents-md/"}], "version": "1.0.0", "reviewed_on": "2026-10-03", "review_status": "reviewed", "next_review_criteria": "The YAML specification, Codex AGENTS.md behavior, or portable package contract changes.; A cited primary source is materially revised, replaced, or becomes unavailable.; Repeated learner results show that the exercise or success criteria are ambiguous.", "canonical_aliases": ["/yaml-rules-for-ai-agents/", "/agents-md/"], "canonical_url": "https://teachthecompany.com/school/structured-rules-yaml-and-agents-md/"}