Phoenix Project Guide

phoenix_project_guide is an agentic documentation template for Elixir projects built with Phoenix and Ecto. It provides reusable Markdown templates, instructions for AI agents, and engineering guides to help people and agents document requirements, model the domain, define architecture, and verify and deliver changes.

It supports both single applications and umbrella projects. Adapt its templates to your project's actual requirements, conventions, and verification commands; the guides cover development workflow, clean code, persistence, interfaces, testing, and operations.

Step for humans

To your current project agent, say:

Integrate phoenix_project_guide following its README. Generate the documentation using its templates and adapt AGENTS.md to the project. Ask me any questions needed to fill in missing information.

Documentation for agents

This folder contains guides and templates for documenting a project and directing AI agents. Active documents describe your project; the guides provide general engineering principles. Keep all documentation in this folder in English.

Where each Markdown file belongs

Use the same structure for a single application and an umbrella. Place shared documentation at the repository root:

<project root>/
  AGENTS.md
  README.md
  docs/
    REQUIREMENTS.md
    DOMAIN.md
    ARCHITECTURE.md
    DELIVERY_CHECKLIST.md
    decisions/
      0001-initial.md
    phoenix_project_guide/
      README.md
      DEVELOPMENT_WORKFLOW.md
      DOMAIN_MODELING.md
      ARCHITECTURE.md
      CLEAN_CODE.md
      PERSISTENCE.md
      INTERFACES.md
      TESTING_AND_QUALITY.md
      OPERATIONS.md
      templates/
        AGENTS.md
        REQUIREMENTS.md
        DOMAIN.md
        ARCHITECTURE.md
        DELIVERY_CHECKLIST.md
        DECISION.md

Document	Purpose
AGENTS.md	Agent instructions: required reading, project conventions and mandatory checks
README.md	Project introduction for people and links to its documentation
docs/REQUIREMENTS.md	Scope, requirements, acceptance criteria and roadmap
docs/DOMAIN.md	Vocabulary, entities, business rules and responsibilities
docs/ARCHITECTURE.md	Actual project structure, modules and allowed dependencies
docs/DELIVERY_CHECKLIST.md	Required delivery checks and their results
docs/decisions/*.md	Significant decisions, their reasons and consequences
docs/phoenix_project_guide/*.md	General engineering guides to consult according to the task
docs/phoenix_project_guide/templates/*.md	Original templates for generating active project documents

In an umbrella, these documents remain at the root, alongside apps/. You can add an AGENTS.md inside each application when it needs specific instructions, without duplicating shared documentation.

How to prepare the documents

1. Place this folder at docs/phoenix_project_guide/.
2. Copy the REQUIREMENTS.md, DOMAIN.md, ARCHITECTURE.md and DELIVERY_CHECKLIST.md templates into docs/, keeping their names.
3. Copy templates/DECISION.md to docs/decisions/0001-initial.md. Use a new copy with a numbered filename for each subsequent decision.
4. Have the agent fill the copies with actual project information. Preserve the original templates for reuse. Ask for missing information instead of inventing requirements or decisions.
5. Use templates/AGENTS.md as the starting point for root AGENTS.md. Have the agent adapt its placeholders, code paths, framework rules and verification commands to the actual project. Merge with existing instructions if the file exists.

What to include in AGENTS.md

Storing documents in docs/ does not itself tell an agent to read them. The AGENTS.md template includes documentation instructions and general Elixir, Phoenix, Ecto and testing rules. Adapt those rules to the project. Its documentation instructions include the following:

# Instructions for agents

- Before changing code, read docs/REQUIREMENTS.md, docs/DOMAIN.md
  and docs/ARCHITECTURE.md.
- Consult task-related decisions in docs/decisions/.
- Use docs/phoenix_project_guide/README.md to locate relevant engineering guides.
- Use docs/phoenix_project_guide/templates/ to generate missing project documents
  at the locations specified in that README. Preserve existing content
  when updating documents and keep the original templates unchanged.
- Use actual project information; ask when necessary information is missing.
- Follow docs/DELIVERY_CHECKLIST.md to verify and deliver changes.
- Respect project-specific decisions when applying general guidance.
- Update active documentation when requirements, rules or architecture change.

Add the project's actual conventions and verification commands here. If an AGENTS.md already exists, integrate these instructions into its content.

Which guide to consult

Guide	Topic
DEVELOPMENT_WORKFLOW.md	Work from requirements through delivery
DOMAIN_MODELING.md	Domain modeling and business rules
ARCHITECTURE.md	Code placement and dependencies
CLEAN_CODE.md	Responsibilities, clarity and types
PERSISTENCE.md	Persistence, constraints and transactions
INTERFACES.md	HTTP contracts, LiveView and other entry points
TESTING_AND_QUALITY.md	Tests, isolation and checks
OPERATIONS.md	Operation, deployment and recovery

Guide code snippets illustrate general principles. Application-specific information belongs in the active documents under docs/.