AGENTS.md Template for URL Shortener System Design

Overview

The AGENTS.md template is an operating manual for AI coding agents that governs a URL Shortener System Design. It supports both single-agent execution and multi-agent orchestration, with clear roles, memory rules, and handoff patterns to maintain alignment across the workflow.

Direct answer: This template provides a complete, copyable AGENTS.md block and project-level operating context for building, validating, deploying, and governing a URL shortener system using AI agents.

When to Use This AGENTS.md Template

When you are designing a URL shortener system that relies on AI coding agents for planning, implementation, testing, and deployment.
When you need explicit multi-agent orchestration patterns with defined handoffs and escalation paths.
When enforcing tool governance, security constraints, and production-change controls within agent workflows.

Copyable AGENTS.md Template

# AGENTS.md
Project role: URL Shortener System Design using AI coding agents; supports single-agent and multi-agent orchestration.

Agent roster and responsibilities:
- Planner: defines goals, success criteria, constraints, plan, and drives multi-agent coordination.
- Implementer: translates plan into code changes, data models, API endpoints, and integration hooks.
- Researcher: gathers requirements, API documentation, constraints, and domain insights.
- Tester: creates validation tests, executes them, and records results.
- Reviewer: reviews outputs for quality, security, and compliance.
- Domain Specialist: provides domain-specific rules (URL formats, TTL policies, anti-abuse constraints).

Supervisor or orchestrator behavior:
- The Orchestrator receives the high-level objective, assigns tasks, tracks progress, enforces deadlines, and coordinates handoffs between agents.
- Maintains a single source of truth for the current plan, decisions, and artifacts.

Handoff rules between agents:
- Input to Output: Each agent must produce defined artifacts with input data, context, and a memory key for the next handoff.
- Handoffs must include validation checks, updated memory, and a clear owner.

Context, memory, and source-of-truth rules:
- Use a workspace memory store (project-memory) with scoped items and TTLs.
- Source-of-truth: code repository, issue tracker, design docs, and API specifications; memory must reference SOT data sources.

Tool access and permission rules:
- Tools: Git, REST APIs, cloud services, and CI/CD; provisioned through approvals and least-privilege access.
- Do not grant production credentials through chat; use secrets vaults and rotation policies.

Architecture rules:
- Microservices with API gateway; URL shortening service, analytics, caching, and auth components; asynchronous tasks via message queues where appropriate.

File structure rules:
- Keep only relevant folders; avoid duplication; document changes in a changelog.

Data, API, or integration rules:
- Define data schemas for URLs, click events, and analytics; standardize API contracts; respect rate limits and backoff policies.

Validation rules:
- Validate via unit tests, integration tests against mock services, and contract tests for API boundaries.

Security rules:
- Encrypt sensitive data at rest and in transit; use scoped access; rotate keys; audit trails for changes.

Testing rules:
- End-to-end tests for critical flows; regression tests; load tests under defined thresholds.
- CI/CD pipeline enforces checks and reproducible builds.

Deployment rules:
- Incremental deployments, feature flags, and rollback paths; monitor post-deploy metrics.

Human review and escalation rules:
- Automatic guardrails for critical changes; escalate to humans for policy exceptions or risk events.

Failure handling and rollback rules:
- Rollback to last known-good deployment; revert config changes; preserve for audit.

Things Agents must not do:
- Do not modify production data directly; do not bypass approvals; do not perform unsanctioned changes; do not ignore security constraints.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to maximize reliable automation while preserving human oversight where required. Planner coordinates, Implementer executes within defined guardrails, and Reviewer and Tester provide checks before handoff to Production via an Orchestrator-controlled process. Domain Specialists provide specialist guidance when needed. Escalation paths to human review are defined for policy, security, or risk concerns.

Recommended Project Structure

The following directory tree focuses on the URL shortener workflow and AI agent orchestration context.

ai-url-shortener/
  - agents/
    - planner/
      - plan.md
    - implementer/
      - tasks/
    - tester/
      - tests/
    - reviewer/
      - reviews/
    - researcher/
      - docs/
    - domain-specialist/
      - guidelines/
  - orchestrator/
  - services/
    - url-shortener/
      - src/
      - tests/
    - gateway/
    - analytics/
  - data/
  - docs/
  - scripts/

Core Operating Principles

Single source of truth for decisions, artifacts, and memory.
Explicit, checkable handoffs between agents with clear ownership.
Idempotent actions and traceable outputs.
Memory scoped to the current project/workspace with defined retention.
Security-first design with least-privilege access and auditable changes.

Agent Handoff and Collaboration Rules

Planner informs Implementer of plan, constraints, and acceptance criteria; orchestrator supervises handoffs.
Researcher feeds requirements to Planner and Domain Specialist; outputs go into shared context.
Domain Specialist provides policy constraints to Planner and Implementer; handoffs record rules and edge cases.
Implementer delivers code changes with documentation; Reviewer validates.
Tester provides test cases and validates against acceptance criteria; Escalation to Planner if tests fail.
All agents keep the Orchestrator informed of progress and blockers.

Tool Governance and Permission Rules

All tool usage is subject to least-privilege and approval gates.
Secrets must never be exposed in memory or chat; use vaults and encryption.
Code changes require review and CI checks before merge to production branches.
Production actions require explicit approvals and can be rolled back by the Orchestrator.
Access to data, APIs, and services is logged and auditable.

Code Construction Rules

Write modular, testable code; follow established naming conventions and contracts.
Maintain idempotency for repeated runs; avoid side effects without explicit intent.
Document decisions in the memory store and changelog.
Use typed schemas for data contracts; validate inputs and outputs.
Log decisions and results with traceable IDs; do not leak secrets in logs.

Security and Production Rules

Encrypt secrets; rotate keys; enforce access controls and network segmentation.
Monitor for anomalies; implement safe defaults and fail closed in critical paths.
Use feature flags for production changes; require approvals for breaking changes.
Backups and disaster recovery plans are in place; test restores regularly.

Testing Checklist

Unit tests cover individual components and contracts.
Integration tests validate interactions between services and data stores.
End-to-end tests simulate user flows and AI agent handoffs.
Performance and load tests meet defined targets; monitor latency and error rates.
CI/CD pipeline enforces checks and reproducible builds.

Common Mistakes to Avoid

Ambiguously defined goals or missing acceptance criteria.
Skipping explicit handoffs or memory management between agents.
Bypassing governance or attempting production changes without approvals.
Unbounded memory growth or data leakage through logs or memories.
Lack of security controls or insecure handling of secrets.

FAQ

What is the purpose of this AGENTS.md Template for URL Shortener System Design?

It provides a copyable, project-level operating manual that governs AI coding agents and multi-agent orchestration for URL shortener design, including roles, handoffs, and governance.

How do agent handoffs work in this template?

Handoffs are explicit artifacts with input data, context, ownership, and checkpoints. Each handoff updates the workspace memory and references the source-of-truth data.

What governance is enforced for tool access and secrets?

Access is least-privilege with approvals; secrets reside in vaults, with rotation and audit trails; production actions require orchestrator-approved gates.

How are memory and source of truth maintained?

Memory items live in a scoped project memory store; source-of-truth data sources include code repositories, design docs, and API specs; memory entries reference SOT sources with immutable IDs where possible.

How do we handle failures and rollback in production?

Failures trigger a rollback to the last known-good deployment, with feature flags and approved rollbacks; the orchestrator logs the incident and notifies stakeholders.

Target User

Use Cases