AGENTS.md Template: File Storage Architecture

Overview

Direct answer: This AGENTS.md template provides a complete operating manual to govern both single-agent execution and multi-agent orchestration for a file storage architecture. It guides AI coding agents through planning, provisioning, governance, validation, and recovery in cloud or on-prem environments, including how memory, sources of truth, and handoffs are managed across planner, implementer, tester, and reviewer roles.

The AGENTS.md Template for File Storage Architecture is designed to scale from a single-agent task to multi-agent workflows, enabling coordinated changes to storage layout, lifecycle management, backups, replication, and policy enforcement. It codifies who does what, when, and how, and it provides concrete constraints to prevent drift and unsafe actions while preserving auditable traces for compliance and incident response.

When to Use This AGENTS.md Template

• You need a reproducible, auditable way to design and deploy file storage infrastructure (on cloud or on-prem).
• You require strict guardrails for data residency, access control, backups, and lifecycle policies across multiple storage tiers.
• You are coordinating multiple AI agents (planner, implementer, tester, reviewer, researcher) with clear handoffs and a shared memory of the truth source.
• You want a concrete, copyable operating manual that engineers can paste into AGENTS.md to standardize workflows across projects.

Copyable AGENTS.md Template

# AGENTS.md

Project role
- Storage Architect Lead: Defines architecture, policy guards, and verification criteria.
- Cloud Engineer: Provisions storage resources, permissions, and lifecycle rules.
- Policy & Compliance Agent: Enforces data residency, encryption, and access controls.
- Integrity & Audit Agent: Verifies backups, checksums, and data availability.
- Domain Specialist (Data Ops): Handles metadata, lineage, and data governance specifics.
- Human Reviewer: Performs final validation and sign-off for production changes.

Agent roster and responsibilities
- Planner: Produces the end-to-end plan for storage architecture changes, including risk assessment and rollback strategy.
- Implementer: Executes provisioning, policy updates, and configuration changes according to the plan.
- Tester: Runs functional and resilience tests, validates backups, and checks for data integrity.
- Reviewer: Audits changes against compliance and architecture rules; approves or requests changes.
- Researcher: Gathers requirements, maps dependencies, and documents metadata model and lineage.
- Domain Specialist: Ensures domain-specific constraints (data residency, regulatory requirements) are enforced.

Supervisor or orchestrator behavior
- The Orchestrator enforces sequence and gating: Planner → Implementer → Tester → Reviewer.
- All actions must be idempotent and auditable; the orchestrator halts on policy violations or failed tests.
- Orchestrator stores a single source of truth for the current plan, state, and outcomes.

Handoff rules between agents
- Handoff from Planner to Implementer triggers provisioning scripts with the plan’s exact parameters.
- Handoff from Implementer to Tester exposes the new config and verification artifacts.
- Handoff from Tester to Reviewer requires test results, backup validation, and a summary of changes.
- Handoff to Domain Specialist or Researcher occurs when requirements or metadata changes are identified.

Context, memory, and source-of-truth rules
- All decisions reference the central storage-config repository as the single source of truth.
- Memory is stored in a dedicated context store with versioned checkpoints for each deployment cycle.
- All changes must be traceable to a plan ID and an artifact hash.

Tool access and permission rules
- Agents may read storage policies, run provisioning scripts, read-and-write to configuration endpoints, and call backup APIs.
- Secrets must be retrieved from a vault service and never stored in plain text in memory or logs.
- Write access to production storage config requires a human-approved promote gate.

Architecture rules
- Use a modular, layered storage stack with clearly separated concerns (data plane, control plane, policy plane).
- Prefer declarative, idempotent operations and immutable plan artifacts.
- All changes must be validated against a test suite before production.

File structure rules
- Maintain a single repository for file storage architecture with a dedicated environment folder per stage (dev, staging, prod).
- Organize by capability: topology, backups, lifecycle, access, and metadata.
- Keep policy definitions alongside implementation to minimize drift.

Data, API, or integration rules when relevant
- All API calls must be authenticated and authorized; use short-lived tokens.
- Backups and replication must be verified after deployment; metadata changes should propagate consistently.
- Integrations with external services must be documented and versioned.

Validation rules
- Validate topology against design specs; verify replication, backup integrity, and access controls.
- Run end-to-end tests for provisioning, policy application, and rollback scenarios.
- Ensure idempotency and deterministic outputs for repeat runs.

Security rules
- Never store secrets in logs; rotate credentials on schedule.
- Enforce least privilege for all agents; use role-based access control.
- Enforce encryption at rest and in transit where applicable.

Testing rules
- Unit tests for individual scripts and policy checks.
- Integration tests for storage API, vault, and backup services.
- End-to-end tests for provisioning, policy enforcement, and rollback.

Deployment rules
- Deploy changes through a staged pipeline with guardrails and approvals.
- Maintain a rollback plan and tested restore point for production changes.
- Log all deployment steps with traceable plan IDs.

Human review and escalation rules
- Trigger human review for non-idempotent changes or failed tests.
- Escalate to domain experts if regulatory requirements are impacted.
- Maintain an escalation path for production incidents.

Failure handling and rollback rules
- If tests fail, revert to the previous known-good state and re-run validation.
- Snapshot configurations before applying changes.
- Ensure backups are intact before and after changes.

Things Agents must not do
- Do not bypass policy checks or security controls.
- Do not apply changes in production without explicit approvals.
- Do not ignore drift between plan and actual state.
- Do not introduce untested code into production.

Recommended Agent Operating Model

The recommended operating model defines distinct roles and boundaries for single-agent execution and multi-agent orchestration. Planner defines strategy, Implementer executes changes, Tester validates outcomes, and Reviewer authorizes production deployment. In multi-agent orchestration, the Domain Specialist and Researcher augment the core cycle by ensuring regulatory alignment and metadata completeness. Escalation paths are clearly defined to involve a human reviewer for high-risk decisions.

Recommended Project Structure

storage-architecture-agents/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── tester/
│   ├── reviewer/
│   ├── researcher/
│   └── domain-specialist/
├── policies/
├── plans/
├── configs/
├── environments/
│   ├── dev/
│   ├── staging/
│   └── prod/
├── metadata/
├── backups/
└── tests/

Core Operating Principles

• Single source of truth with versioned plans and artifacts.
• Idempotent, auditable, and reproducible actions across agents.
• Explicit handoffs with context and justification preserved.
• Strong separation of duties for security and compliance.
• Guardrails that prevent unsafe production changes without approval.

Agent Handoff and Collaboration Rules

• Planner to Implementer: include exact plan, required parameters, and rollback criteria.
• Implementer to Tester: provide build artifacts, test results, and environment offsets.
• Tester to Reviewer: deliver validation report with pass/fail status and remediation steps.
• Domain Specialist/Researcher involvement when scope changes or regulatory constraints apply.

Tool Governance and Permission Rules

• Commands to provision or modify storage must be governed by role-based access control.
• All edits to config and policy require audit trails and approvals when moving to prod.
• Secrets must be retrieved from a vault service and never cached in plain text.
• Access to production resources is limited and requires multi-factor verification.
• External service calls must be logged and rate-limited to prevent abuse.

Code Construction Rules

• Follow declarative and idempotent patterns for all provisioning steps.
• All scripts must be tested in a staging environment before production deployment.
• Keep configuration-driven with explicit defaults and environment-specific overrides.
• Document every change with a plan ID and rationale in the AGENTS.md template.

Security and Production Rules

• Encrypt data at rest and in transit; rotate keys regularly.
• Enforce least privilege and segregate duties across agents.
• Monitor and alert on anomalies in storage usage, replication, or access patterns.

Testing Checklist

• Unit tests for provisioning and policy scripts.
• Integration tests for storage API calls, vault access, and backups.
• End-to-end tests for plan execution, handoffs, and rollback handling.
• Security tests for access controls and encryption.
• Production-readiness checks and runbooks validated by humans.

Common Mistakes to Avoid

• Skipping validation or bypassing the guardrails for speed.
• Drift between planned state and actual state without traceability.
• Storing secrets in memory or logs without proper protection.
• Overloading the orchestrator with non-idempotent actions.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is the purpose of this AGENTS.md Template for File Storage Architecture?

It provides a copyable operating manual that governs single-agent and multi-agent workflows for designing, provisioning, and validating a file storage architecture with clear handoffs and guardrails.

How are handoffs between agents managed in this template?

Handoffs occur with explicit plan details, environment context, and justification; the orchestrator enforces sequence and validates results before proceeding.

What strong security practices are required in this workflow?

Secrets must be retrieved from a vault, access must follow least-privilege policies, and data must be encrypted at rest and in transit with auditable logs.

When should human review be triggered?

Human review is triggered for non-idempotent changes, failed validations, policy violations, or regulatory-impacting modifications.

How is rollback handled in case of failure?

Rollback reverts to the last known-good state, with backups validated and plan artifacts versioned for traceability.