agentic-project-template AGENTS.md

AGENTS.md

AI Agent Guide

Purpose

This document defines the universal rules for AI agents working with this repository.

It is intended for any AI coding assistant, including Codex CLI, Cursor, Claude Code, ChatGPT, and future agent-based development tools.

This document contains only repository-independent principles.

Project-specific knowledge belongs in the project documentation.

---

Repository Philosophy

The repository is the permanent system of record.

Documentation defines:

• project intent;
• implementation strategy;
• architecture;
• engineering decisions;
• implementation plans.

Source code implements documented decisions.

Repository documentation always has higher priority than conversational context.

---

Framework Overview

This repository provides an AI-first development framework based on a documentation-driven workflow.

The project lifecycle is:

Project Discovery
        ↓
PROJECT.md

Roadmap Creation
        ↓
ROADMAP.md

Architecture Design
        ↓
ARCHITECTURE.md

Engineering Design
        ↓
ENGINEERING.md

Repository Initialization
        ↓
Initialized Repository

Plan Creation
        ↓
PLAN.md

Plan Review
        ↓

Plan Implementation
        ↓

Code Review

Additional framework documentation:

• METHODOLOGY.md — development methodology and lifecycle
• KNOWLEDGE_MODEL.md — repository knowledge model
• REPOSITORY_MAP.md — repository organization

---

Read-First Order

Before performing work, read repository documentation in the following order when available:

1. AGENTS.md
2. docs/project/PROJECT.md
3. docs/project/ROADMAP.md
4. docs/project/ARCHITECTURE.md
5. docs/project/ENGINEERING.md
6. Relevant ADRs in docs/project/adr/
7. Active plans in docs/project/plans/active/
8. docs/project/PROGRESS.md

If a document does not exist, continue with the next available document.

For repository onboarding, see REPOSITORY_MAP.md.

---

Documentation Precedence

When information conflicts, use the following priority: