What Matters
AGENTS.md can reduce the time an agent spends rediscovering how a repository works. Its value depends on accurate commands, clear scope, useful verification steps and maintained instructions. DN’s instruction-readiness framework turns those requirements into evidence questions. The accompanying worksheet records what you have checked; it does not scan a repository, enforce permissions or certify the resulting code.
DN Evidence Block
- Last verified: 19 October 2026. The 2027 title is an editorial planning horizon, not a future observation date.
- Scope: The open AGENTS.md format and the current Codex instruction-discovery documentation.
- DN contribution: A repository instruction evidence rubric and local readiness worksheet with explicit unknown states.
- Limits: No repository was cloned, scanned or executed for this article. No correlation between instruction quality and development ROI was measured.
- Prepared by: Decentralised News research desk. No independent reviewer is claimed. Submit a correction.
A repository has an instruction surface
A new coding agent needs to discover where the application starts, how dependencies are installed, which tests matter and what changes are outside its remit. When that information is absent or stale, the agent may spend more effort reconstructing conventions—or confidently run the wrong command. AGENTS.md offers a predictable place for this context.
The open format describes ordinary Markdown instructions, including build/test conventions and nested files for scoped guidance. Codex documents its own discovery and precedence rules. Those product-specific rules matter: support for a filename does not prove identical loading behavior, limits or precedence in every tool.
For an agent that prepares financial infrastructure changes, instruction quality is connected to operational discipline. A correct unit-test command, an explanation of a simulated payment environment and an explicit boundary around production secrets can make intended work easier to understand. The file remains guidance; the actual permission boundary belongs elsewhere.
The economy is maintenance, not file creation
Creating a document is cheap. Keeping it aligned with the repository as package scripts, test fixtures and deployment requirements change is recurring work. A useful service therefore needs observable deliverables: commands that still run in the declared environment, instruction scope that is understandable, and a reviewer who can identify unsupported or dangerous directions.
DN’s commercial hypothesis is that maintained instruction evidence can become a procurement and onboarding signal. That is not proof that buyers already pay for a certification or that an instruction file automatically improves model selection. A credible offering should sell bounded work and show its evidence, not promise universal agent readiness.
The DN Agent Instruction Readiness Rubric
| Area | What useful instructions cover | Evidence beyond the prose |
|---|---|---|
| Discovery and scope | Root and relevant nested instruction files are located; tool-specific loading is checked. | Version-pinned discovery record for the directories in scope |
| Environment and dependencies | Supported runtime, installation steps and required services are explicit. | Fresh setup in a clean declared environment |
| Build and checks | Commands, fixtures and expected outcomes are actionable. | Dated command output with exit status and limitations |
| Authority and secrets | Production changes, network use and secret access boundaries are clear. | Independent permission configuration; no embedded credentials |
| Nested consistency | Subproject guidance does not silently contradict the parent or actual workflow. | Reviewed scope map and resolved conflicts |
| Acceptance and recovery | Completion conditions, escalation and rollback instructions are practical. | A bounded example showing how uncertainty is reported |
| Freshness and ownership | An owner and review trigger keep guidance current. | Source revision, review date and relevant change history |
Instructions cannot grant themselves authority
A repository file can contain an incorrect or malicious direction. Treating every sentence as authorization would let content expand the agent's access. A reliable workflow distinguishes project guidance from the user's task, the tool's permission model and the environment's actual enforcement.
Do not put passwords, recovery phrases or production keys in the file. Do not tell an agent to suppress test failures or label an unrun check as passed. State the escalation path when a required dependency, fixture or permission is missing. Instructions can explain the limit; independent controls must enforce it.
DN Agent Instruction Readiness Worksheet
Record your own evidence for one pinned workflow. These are your declarations, not DN findings, a safety score or a scan. Unknown is the default. Do not enter credentials or private task content.
All boundaries start unknown. The surrounding table explains what evidence to collect; this worksheet does not inspect a provider.
Runs locally with no account, wallet, model call or storage of your answers. A downloaded worksheet contains your selections. Normal DN site analytics are separate.
A useful first review
- Choose one repository revision and the specific agent/tool configuration.
- Map root and nested instructions for the directories the task will touch.
- Run setup and a small relevant check in an isolated environment; record failures without rewriting them as success.
- Compare the commands and acceptance conditions with the actual package and CI configuration.
- Review secret handling and permission boundaries separately from instruction prose.
- Assign an owner and a review trigger for dependency, build, deployment or policy changes.
These steps describe a proposed audit workflow. Selecting “I hold relevant test evidence” in the worksheet does not make DN the auditor or validate a trace. A versioned record should say what was run, what was not run and what the result can support.
Where this fits in the agentic web
Website discovery metadata helps agents find a publisher or capability. Repository instructions help a coding agent work within a project. Publisher verification concerns identity and provenance; a spending policy concerns an allowed effect. These layers can complement each other, but one should not substitute for another.
Connect the rubric to DN’s Agentic Web Readiness Index, while keeping repository instruction readiness a distinct category. Use the Runtime Portability framework when the agent's surrounding infrastructure also needs to move.
DN Alpha Thesis
The durable asset is a maintained relationship between instructions and executable evidence. A repository can be easy for an agent to understand yet still be insecure or incorrect. Keeping those claims separate gives a readiness product something useful to measure without inventing assurance.
Methodology, limitations and change log
Version 0.1, 19 October 2026. DN reviewed the open format and a product-specific discovery guide, then designed an original evidence rubric. This edition is a manual worksheet, not the promised future repository scanner. No universal scoring weights or vendor results are published. Any later scanner should distinguish file detection, semantic review and commands actually executed, and obtain explicit authorization before running code.
To discuss a bounded instruction review or submit a corrected example, contact DN. A paid engagement must state the repository revision and deliverables; it cannot purchase an independent readiness finding.
Primary sources
Frequently asked questions
Does an AGENTS.md file enforce security restrictions?
No. Instructions are context. Enforce permissions, secrets access and production changes through independent controls.
Can this worksheet scan a repository?
No. It records the reader’s declared evidence for a repository. It does not fetch, execute or inspect repository files.
Does a high readiness count prove an agent will succeed?
No. Instruction coverage is not measured task performance, code correctness or assurance that every agent follows the same discovery rules.
Disclosure: Educational research, not investment advice or a security certification. No affiliate or sponsored placement appears in this edition. DN may discuss scoped research services; payment cannot purchase a finding. Corrections should identify the affected claim, observation date and supporting source.
