AGENTS.md Template for Distributed File System Design

Overview

Direct answer: This AGENTS.md template governs the distributed DFS agent workflow by defining roles, memory, and handoffs, enabling both single-agent and multi-agent collaboration.

The AGENTS.md template for distributed file system design provides a single source of truth for how AI coding agents operate across a DFS project. It codifies operating model, handoffs, tool governance, and human review to ensure predictable, auditable behavior in multi-node environments.

When to Use This AGENTS.md Template

• When designing an AI-driven distributed file system and you need clear agent roles and handoffs.
• When coordinating a planner, implementer, tester, researcher, and domain specialist across nodes.
• When you require strong tool governance, memory persistence, and a single source of truth for decisions and results.
• When you want a copyable operating context that can be versioned and shared across teams.

Copyable AGENTS.md Template

# AGENTS.md
Project role: Distributed DFS Design Agent
Agent roster and responsibilities:
- Planner: defines goals, path to achievement, and coordinates workload across agents.
- Implementer: makes changes to DFS components, applies architecture rules, and writes code.
- Researcher: gathers external references, validations, and test cases; curates sources of truth.
- Reviewer: verifies correctness, ensures security and compliance, and approves changes for deployment.
- Domain Specialist: provides domain-specific constraints (e.g., storage backend, consistency model, security requirements).
Supervisor or orchestrator behavior:
- The Orchestrator maintains memory, enforces memory memory invariants, and routes tasks between agents.
- Enforces deadlines, validates outputs, and triggers escalation when anomalies are detected.
Handoff rules between agents:
- Planner → Implementer: hand off goals, acceptance criteria, and architectural decisions with a complete context snapshot.
- Implementer → Reviewer: hand off completed changes and test results; include a summary of risks and mitigations.
- Reviewer → Orchestrator: reports pass/fail and, if failed, returns to Planner with gaps.
- Domain Specialist → Planner: shares domain constraints and updates knowledge after review.
Context, memory, and source-of-truth rules:
- All decisions, results, and references are stored in a versioned workspace with a single memory store.
- The source of truth includes design documents, API specs, and test results.
Tool access and permission rules:
- Agents may access read/write to the DFS project workspace; API calls are restricted to approved endpoints.
- Secrets are injected through a secure vault; no agent prints secrets to logs.
Architecture rules:
- Use a modular DFS architecture with clear separation of concerns: metadata service, storage layer, replication, and client API.
File structure rules:
- Structure mirrors DFS components and agent roles; no unrelated folders.
Data, API, or integration rules when relevant:
- All external calls require authentication tokens; rate limits and retries are implemented.
Validation rules:
- All changes must pass unit and integration tests; replication must maintain consistency guarantees.
Security rules:
- Enforce least privilege, encryption at rest and in transit, and role-based access controls.
Testing rules:
- Include unit tests, integration tests for cross-node replication, and end-to-end scenario tests.
Deployment rules:
- Changes are deployed via a controlled pipeline with canary and rollback support.
Human review and escalation rules:
- Human in the loop for high-risk changes; escalation path documented.
Failure handling and rollback rules:
- On failure, rollback to last good snapshot; alert on anomalies; preserve audit trails.
Things Agents must not do:
- Do not bypass the orchestrator; do not leak secrets; do not perform unsanctioned modifications to storage nodes.

Recommended Agent Operating Model

Roles and decision boundaries: Planner drafts goals and constraints; Implementer enforces design, Researchers validate assumptions; Reviewers audit outputs; Domain Specialist injects domain constraints. Escalation paths: if validation fails, escalate to human reviewer and then to project lead.

Recommended Project Structure

root/
  orchestrator/
  agents/
    planner/
    implementer/
    researcher/
    reviewer/
    domain-specialist/
  storage/
  metadata/
  replication/
  api/
  docs/
  tests/

Core Operating Principles

• Single source of truth for DFS design decisions and memory.
• Strict memory discipline: decisions, context, and sources of truth are versioned and auditable.
• Clear handoff protocol with formal criteria and context transfer.
• Tools and secrets are accessed via secure, auditable channels.
• Actions must be explainable and repeatable; no hidden step-taking.

Agent Handoff and Collaboration Rules

Concretely define how planners, implementers, testers, researchers, reviewers, and domain specialists collaborate, including escalation triggers.

Tool Governance and Permission Rules

Define commands, file edits, API calls, secrets handling, production access, and approval gates.

Code Construction Rules

Be specific about DFS components, APIs, serialization formats, and repository conventions; avoid vague language.

Security and Production Rules

Security guidelines tailored to DFS environments, including encryption, access controls, and incident response.

Testing Checklist

• Unit tests for each DFS component and memory store.
• Integration tests for cross-node replication and client API.
• End-to-end tests simulating node failures and recovery.
• Canary deployment checks and rollback readiness.

Common Mistakes to Avoid

Common mistakes teams make with this agent workflow or orchestration pattern and how to avoid them.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages.

FAQ

What is the AGENTS.md Template used for distributed DFS?

The template defines roles, handoffs, and governance for AI coding agents operating in a distributed file system design context.

Who should be on the agent roster?

Planner, Implementer, Researcher, Reviewer, and Domain Specialist, with an orchestrator overseeing workflows.

How are handoffs handled between agents?

Handoffs transfer context, memory, and decision logs with acceptance criteria; the next agent receives a complete snapshot.

What are the security constraints?

Secrets must be kept in vaults, access is least-privilege, and all data in transit and at rest is encrypted.

How is validation performed?

Unit and integration tests verify components; end-to-end tests validate multi-node interactions and replication guarantees.