AGENTS.md Template for Object Storage System Design | Suhas Bhairav

Overview

AGENTS.md template for object storage system design defines the operating context, agent roles, and governance for AI coding agents. It supports single-agent work and multi-agent orchestration with explicit handoffs and source of truth rules.

When to Use This AGENTS.md Template

Design scalable object storage architectures such as S3 compatible APIs, multi region replication, and metadata strategies
Coordinate AI coding agents across planning, design, validation, and deployment with clear handoffs
Establish tool governance, security boundaries, and human review gates for storage prototypes

Copyable AGENTS.md Template

# AGENTS.md

Project role: Object Storage System Design across AI coding agents

Agent roster and responsibilities:
- Planner: captures requirements, constraints, and guides design decisions
- Architect: translates requirements into system design including storage tiers, replication, and metadata
- Security Reviewer: validates encryption, access control, threat modeling
- Data Modeler: defines object metadata and namespace
- Tooling & DevOps: defines CI CD and deployment scripts
- Validator: runs tests and ensures compatibility
- Researcher: collects external references and standards

Supervisor or orchestrator behavior:
The orchestrator coordinates tasks, enforces memory, enforces tool governance, triggers handoffs, and escalates when human review is needed

Handoff rules between agents:
- Planner -> Architect when requirements are frozen
- Architect -> Security Reviewer and Data Modeler for design validation
- Security Reviewer and Data Modeler -> Tooling & DevOps for implementation
- Tooling & DevOps -> Validator for verification
- Validator -> Deployable Release Manager for deployment
- If any feedback mandates changes, cycle back to the responsible agent and reset the handoff

Context memory and source of truth rules:
- Maintain a central memory store containing design decisions, requirements, API specs, and test results
- Source of truth: design specs, requirements, API references, test plans

Tool access and permission rules:
- Planner: read write to planning area; no secrets
- Architect: read write design docs; read API references
- Security Reviewer: read sensitive configs; write security notes; no keys
- Data Modeler: read write metadata schemas
- Tooling & DevOps: read write CI CD and deployment scripts; manage infrastructure as code
- Validator: run tests; no production changes
- Researcher: read access to external references; no production changes

Architecture rules:
- Define modular components, clear interfaces, stateless workers where possible
- Use versioned APIs and backward compatibility strategies
- Enforce immutable design decisions in the memory store

File structure rules:
- Keep all design docs under design/
- Keep tests under tests/
- Keep infrastructure as code under infra/

Data API and integration rules:
- Align with S3 compatible APIs; document object schema and metadata standards
- Validate API compatibility with integration tests

Validation rules:
- Every design decision must be validated against functional, performance, and security criteria
- All changes require passing tests before approval

Security rules:
- Secrets in a vault; least privilege access; audit logging
- Data at rest encrypted; in transit TLS 1.2+; rotate keys regularly

Testing rules:
- Unit tests for components; integration tests for API compatibility; load and resilience tests for storage layer

Deployment rules:
- Use canary deployment for storage components; feature flags to enable new capabilities

Human review and escalation rules:
- Escalate to lead architect if security concerns arise; require human signoff for breaking changes

Failure handling and rollback rules:
- If validation fails, revert to previous design state and re-run tests; document rollback steps

Things Agents must not do:
- Do not bypass security or secret controls; do not mutate production without approval

Recommended Agent Operating Model

Roles, decision boundaries, and escalation paths for object storage design with AI coding agents. The model supports both single agent operation and multi agent orchestration with clear decision rights and handoff triggers.

Recommended Project Structure

object-storage-design/
├─ design/
│  └─ specs.md
├─ docs/
├─ tests/
│  ├─ unit/
│  └─ integration/
├─ infra/
│  └─ k8s/
├─ src/
│  └─ storage/
└─ README.md

Core Operating Principles

Single source of truth: all decisions and artifacts live in memory and design specs
Deterministic outputs: agents rely on memory and explicit rules
Traceability: every action is auditable with source of truth references
Least privilege: agents access only what is required

Agent Handoff and Collaboration Rules

Planners coordinate with architects and domain experts; handoffs occur at milestone boundaries with explicit context transfer and expected outputs.

Tool Governance and Permission Rules

Commands and edits require explicit approvals when changing production artifacts
Secrets managed via vault; never hard coded
Production changes require human sign off

Code Construction Rules

Code must be modular and well documented
Follow version control and linting rules

Security and Production Rules

Encryption in transit and at rest
Audit logs for all design changes
Access control with least privilege

Testing Checklist

Unit tests for all components
Integration tests for API compatibility
Performance benchmarks for storage throughput and latency
Recovery and rollback tests

Common Mistakes to Avoid

Skipping security reviews
Insufficient memory of design decisions
Unclear handoff rules or ambiguous outputs

FAQ

What is the purpose of this AGENTS.md Template for object storage design?

It defines governance, roles, and handoffs for AI coding agents designing an object storage system and supports both single agent and multi agent orchestration.

Who should use this AGENTS.md Template?

Engineering leaders, AI developers, and SREs building or evaluating object storage deployments with multi agent coordination.

What are the key handoff rules between agents?

Handoffs occur at design milestones: planner to designer, designer to validator, validator to tester, tester to deployer; each handoff preserves context and source of truth.

How is memory and context managed?

A central memory store keeps design decisions, requirements, and artifacts; agents query the memory to avoid duplication and drift.

What are the security and production rules?

Secrets managed by a vault, least privilege access, production gates with approval, auditing, and rollback procedures.

How do I validate the design changes?

Use defined validation rules including unit tests for components, integration tests for API compatibility, and performance benchmarks before deployment.

AGENTS.md template: Object Storage System Design — AGENTS.md Template

Target User

Use Cases