Discussion: standard section for generated-code safety checks

[dgenio]

Context

AGENTS.md gives repositories a place to tell coding agents how to work safely and effectively in a codebase.

As coding agents become more autonomous, many repositories will need to specify not only style and workflow rules, but also the checks that generated code must pass before a human reviews it.

Problem

Agent-authored changes can fail in predictable ways:

• tests not run;
• generated files committed accidentally;
• secrets or local paths leaked;
• package artifacts include unintended files;
• dependency changes are made without justification;
• security scanners are skipped;
• docs/examples drift from code;
• risky commands are run without permission.

Different repositories can describe these expectations manually, but a common recommended section would make AGENTS.md more useful across tools and projects.

Proposal

Would it make sense to document an optional section for generated-code safety checks?

For example:

## Generated-code safety checks

Before submitting changes, agents should:

- run the project test command: `<command>`;
- run lint/type checks: `<command>`;
- inspect generated/package artifacts: `<command>`;
- check for secrets or local-only paths: `<command>`;
- avoid committing files matching: `<patterns>`;
- summarize dependency changes and why they are needed;
- state which checks could not be run.

The section would remain optional and project-specific. The value would be giving maintainers a predictable place to encode safety expectations.

Use cases

• More reliable agent-generated PRs.
• Easier human review.
• Better behavior across multiple coding agents.
• Standard place to document project-specific safety gates.
• Reduced accidental commits of generated artifacts, local files, or secrets.

Non-goals

• Defining one universal safety policy.
• Requiring every repository to use the section.
• Replacing CI.
• Preventing maintainers from using their own structure.

Open questions

• Is this too prescriptive for the current scope of AGENTS.md?
• Should this live in the main example, advanced guidance, or a recipe?
• Should there be separate sections for "must run", "should run", and "state if unable to run"?
• Are there existing conventions this should align with?

[piyushbag]

+1 on an optional standardized section for generated-code safety checks.

Placement: I would keep this out of the minimal starter template and add it to advanced guidance (or a recipe page) so small repos are not overwhelmed. The main example could link to the recipe.

Structure: Three sub-bullets might help maintainers without being prescriptive:

1. Must run before opening a PR — project test command, lint/typecheck.
2. Must inspect — generated artifacts, dependency diff summary, secret/path scan.
3. If unable to run — explicit statement of which checks were skipped and why.

Wording sketch (still project-specific placeholders):

## Generated-code safety checks (optional)

Before opening a PR, run:

- Tests: `<command>`
- Lint / types: `<command>`

Before requesting review, inspect:

- Generated or packaged artifacts: `<command or path>`
- Dependency changes: summarize what changed and why
- Secrets and local-only paths: `<command>`

If a check cannot be run in this environment, say which checks were skipped.

Non-goals alignment: This stays documentation-only and does not replace CI. It gives agents a predictable place to echo what CI will eventually enforce, which should make human review faster.

Open question: Should compatibility listings (agents/tools) reference whether they surface this section to users? That could be a separate compatibility-table column later, not part of the first spec change.

Happy to help draft the recipe page or an example snippet if useful.