Agent Instructions

Coding agents need more than a feature specification. They need to know how the project expects them to work and which approved decisions they must respect. Those expectations might concern engineering practices, approved technology, architecture, component reuse, product goals, documentation, accessibility, or other application-specific constraints.

The SHAPE Framework recommends keeping standing Markdown instruction and context documents together in agent_instructions/. This directory is extensible. Projects may create as many appropriately scoped Markdown files as needed, with descriptive filenames; the framework does not require a fixed list of file names.

A root-level AGENTS.md provides a discoverable entry point for coding agents. Its essential instruction is:

Read and observe all Markdown (.md) files in agent_instructions/ before starting work and throughout implementation.

This root file does not need to enumerate every file. Adding an instruction document should not require maintaining a second list in the entry point.

Every Markdown file placed in agent_instructions/ should begin with a line or heading that states the document's purpose. For example, an organization might provide a file defining approved technologies, a project architecture document, a design-system guide, or a statement of business objectives. Those are examples, not required filenames or a prescribed hierarchy.

A self-describing file makes it easier for both people and agents to determine what rules it contains, and reduces the likelihood that a new document is ignored merely because its filename was not added to a central index.

Standing instructions describe how the agent works and which enduring constraints apply. Product knowledge describes intended behavior and supports independent verification. Keep those concerns separate. The current repository convention uses a separate specifications/ area; internal naming, granularity, and any future directory or master-file mandate remain open to revision. This website's actual requests/current-state organization is a project example, not a compulsory universal structure.

Organizations should decide who may approve changes to controlled instructions and shared standards. An agent should not silently rewrite the rules that govern its work or invent authority to override them. When documents conflict in a consequential way, the Product Engineer and relevant owner must resolve the conflict rather than allowing the agent to choose whichever instruction is easiest.

Instruction files should be concise enough to remain usable, mutually consistent, and kept synchronized with approved decisions. Projects may add domain-specific constraints without altering the discoverability convention.

Instructions can tell an agent not to retrieve secrets or use unauthorized services, but they cannot prevent unauthorized actions if the execution environment grants those capabilities. Permissions and access restrictions belong in technically enforced controls.

A coding agent must not rewrite enduring engineering standards to simplify a feature. Authorized humans can evolve protected rules through controlled decisions; writing “protected” in a file cannot enforce immutability. Repository permissions, reviews and execution controls enforce access. Product-intent maintenance during iteration is normal work and is not permission to modify the standards that govern it.

See the actual root and project instruction examples and core project example. Their scope, source date and uncertain canonical status are explicit; the website's filenames and approval rules are not automatically SHAPE-wide mandates.