AGENTS.md Template for Oracle database architecture

Overview

Direct answer: This AGENTS.md Template defines the Oracle database architecture agent workflow, enabling both autonomous single-agent work and coordinated multi-agent orchestration with clear roles, memory, and governance.

The AGENTS.md template is a project-level operating manual for Oracle database architecture automation. It codifies how AI coding agents collaborate on tasks such as schema design, capacity planning, backup/DR, patch management, performance tuning, and monitoring. It establishes a shared memory model, a single source of truth, and explicit constraints so agents can operate with autonomy while remaining auditable and controllable.

When to Use This AGENTS.md Template

To enable auditable, repeatable Oracle DB architecture automation for single-agent or multi-agent setups.
When you need strict handoff rules between planner, implementer, tester, reviewer, researcher, and domain specialist agents.
When tool governance, memory contexts, and a central source of truth are required for architectural decisions.
When security, validation, and production deployment rules must be codified and enforced.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Oracle DB Architecture Automation Lead
Agent roster and responsibilities:
- Planner: defines tasks, constraints, and milestones for Oracle DB architecture changes.
- Implementer: builds automation (SQL/PLSQL, orchestration scripts, tooling) to implement architecture plans.
- Tester: validates outputs against acceptance criteria and ensures non-regression.
- Reviewer: performs governance checks, ensures compliance with policies, and approves releases.
- Researcher: gathers Oracle best practices, baseline configurations, and reference designs.
- Domain Specialist: provides DBA expertise on Oracle features (RAC, Data Guard, ASM, partitioning).
Supervisor/Orchestrator:
- Orchestrator coordinates all agents, maintains the memory/context, enforces constraints, and handles escalations.

Handoff Rules between Agents:
- All handoffs require a memory snapshot, rationale, and acceptance criteria.
- Handoff occurs only after automated checks pass and manual review is completed when required.
- Each handoff must be anchored to a milestone in the plan.

Context, Memory, and Source-of-Truth Rules:
- Central memory stores design decisions, versioned artifacts, and decision rationales.
- Source-of-truth includes configuration baselines, schema diagrams, and policy documents.
- Do not rely on ephemeral outputs; persist results with timestamps and lineage.

Tool Access and Permission Rules:
- Access limited to Oracle DB tooling, SQL*Plus/SQLcl, RMAN, Oracle Enterprise Manager, and approved CI/CD steps.
- Secrets retrieved from a vault; rotate credentials; do not hard-code.

Architecture Rules:
- Architecture decisions must be justified with reliability, performance, and security trade-offs.
- Prefer idempotent changes; avoid blocking migrations without rollback plans.

File Structure Rules:
- Store architecture artifacts under oracle-database-architecture/artifacts with versioned folders.
- Scripts under oracle-database-architecture/scripts; templates under templates/.

Data, API, or Integration Rules:
- All data operations must be auditable and reversible; use disaster recovery plans for schema changes.
- API or integration points must be documented with input/output schemas.

Validation Rules:
- Validate against acceptance criteria; run regression and performance tests where applicable.
- Ensure changes are idempotent and reproducible.

Security Rules:
- Least privilege for all agents; rotate keys; encrypt sensitive data.

Testing Rules:
- Unit tests for scripts; integration tests for end-to-end changes; deployment tests in staging.

Deployment Rules:
- Use gated deployments; require approvals; validate in staging before prod.

Human Review and Escalation Rules:
- Escalate to domain specialist or human reviewer for high-risk changes; document decisions.

Failure Handling and Rollback Rules:
- Define rollback steps; test rollback in staging; monitor after prod switch.

Things Agents Must Not Do:
- Do not perform production changes without approval.
- Do not bypass memory constraints or skip validations.
- Do not introduce architecture drift.

"Ready for Production" Criteria:
- All sections complete, memory snapshot captured, and approval logged.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to balance autonomy with governance in Oracle DB architecture work. The planner sketches constraints; the implementer creates automation; the researcher collects Oracle best practices; the tester validates; the reviewer governs quality; the domain specialist ensures DBA accuracy; the orchestrator coordinates and enforces governance and escalation when needed.

Recommended Project Structure

Use a workflow-aligned directory tree that keeps Oracle DB architecture artifacts organized.

oracle-database-architecture/
├── agents/
│   ├── planner/
│   ├── implementer/
│   ├── tester/
│   ├── reviewer/
│   ├── researcher/
│   └── domain-specialist/
├── orchestrator/
├── memory/
├── artifacts/
├── scripts/
├── tests/
└── deployments/

Core Operating Principles

Explicit memory and source-of-truth for Oracle DB architecture decisions.
Do not drift context between steps; enforce constraint checks before handoffs.
All tool usage must be logged, auditable, and reversible where possible.
Decisions must be explainable and justified by reliability, performance, and security factors.

Agent Handoff and Collaboration Rules

Handoffs follow milestones: planner → implementer, implementer → tester, tester → reviewer, reviewer → domain specialist for validation, domain specialist → orchestrator for sign-off. Each handoff must include a memory snapshot, rationale, and acceptance criteria; failures trigger escalation to the orchestrator.

Tool Governance and Permission Rules

Commands, file edits, API calls, and secrets access must be permissioned; enforce least privilege; production changes require approvals and a rollback plan; external services use audited gateways; secrets are stored in a vault with rotation.

Code Construction Rules

Code must be idempotent, well-documented, tested, and versioned. Use parameterized templates; avoid hard-coded values; ensure traceability from design to deployment.

Security and Production Rules

Enforce Oracle security best practices: access control, encryption, auditing, and secure credential handling. Production changes require governance gates and rollback readiness.

Testing Checklist

Unit tests for each script/function.
Integration tests for end-to-end architecture changes.
Staging deployment tests and rollback verification.

Common Mistakes to Avoid

Skipping planner constraints or memory-based decisions.
Unclear handoffs or undocumented decisions.
Unsafe shortcuts that bypass validation or governance.

FAQ

What is the purpose of this AGENTS.md Template for Oracle DB architecture?

To codify a repeatable, auditable multi-agent workflow for Oracle DB architecture tasks, including handoffs, memory rules, and tool governance.

How many agents are typically involved in this orchestration?

Commonly 4–6 roles (planner, implementer, tester, reviewer, researcher, domain specialist) with an orchestrator coordinating; scale varies by project.

How are handoffs between agents managed?

Handoffs occur at milestones with memory context, rationale, and acceptance criteria recorded; each handoff requires validated checkpoints.

What security considerations are emphasized?

Limit tool access, use vaults for secrets, enforce least privilege, and require approvals for production changes and credential exposure.

How is validation and production deployment handled?

Validation includes unit/integration tests; production changes follow gated deployment with rollback plans and monitoring.

Target User

Use Cases