Skip to content

docs(team): Add AGENT_GUIDELINES.md — conventions for agents on Stran…#656

Open
mkmeral wants to merge 1 commit intostrands-agents:mainfrom
mkmeral:agent-guidelines
Open

docs(team): Add AGENT_GUIDELINES.md — conventions for agents on Stran…#656
mkmeral wants to merge 1 commit intostrands-agents:mainfrom
mkmeral:agent-guidelines

Conversation

@mkmeral
Copy link
Contributor

@mkmeral mkmeral commented Mar 13, 2026

Adds team/AGENT_GUIDELINES.md — a compact reference for conventions governing AI agents that interact with Strands repositories.

This is the condensed, team/-format version of the guidelines discussed in #523. It distills the review feedback from that PR (48 comments across 7 reviewers) into a scannable reference that lives alongside DECISIONS.md, TENETS.md, and the other team docs.

Guidelines covered:

  • Add Value or Stay Silent — agents act only when they have something concrete to contribute
  • Keep It Short — progressive disclosure, no walls of text, no excessive praise
  • Approvals Need Reasoning — rejections must justify; approvals calibrate to trust level
  • Scope Credentials to the Task — principle of least privilege, never maintainer tokens, think through failure modes broadly
  • Throttle Autonomous Activity — human-compatible pace, business hours preferred, limit active open items
  • Own What You Deploy — named owner responsible for logs, cleanup, iteration, and kill switch
  • Monitor What Agents Do — use existing tools, but visibility is non-negotiable
  • Maintainers Can Pull the Cord — immediate disable, no approval needed
  • Know That Your Agent Works — validate however makes sense (automated, manual, whatever) before deploying; team buy-in required

Also updates team/README.md to include the new document in the contents table.

Related Issues

Condensed version of the design doc in #523

Type of Change

  • New content
  • Content update/revision
  • Structure/organization improvement
  • Typo/formatting fix
  • Bug fix
  • Other (please describe):

Checklist

  • I have read the CONTRIBUTING document
  • My changes follow the project's documentation style
  • I have tested the documentation locally using npm run dev
  • Links in the documentation are valid and working

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

…ds repos

Compact reference capturing agreed-upon conventions from the discussion
in strands-agents#523. Covers:

- Add value or stay silent
- Keep it short, use progressive disclosure
- Scope credentials to the task (principle of least privilege)
- Throttle autonomous activity to a human-compatible pace
- Own what you deploy, monitor what agents do
- Maintainers can pull the cord
- Know that your agent works before deploying

Also updates team/README.md to include the new document.
@github-actions
Copy link
Contributor

Documentation Preview Failed

The documentation deployment encountered an error. Please check the deployment logs for more details.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant