AI Agent Documentation Template

Universal starter template for AI-assisted project documentation and agent profiles. Use it as a foundation for new projects: adapt structure, rules, agent profiles, and technical recommendations to your domain.

---

Project Overview

AI Agent Documentation Template is a comprehensive, production-ready documentation framework designed for AI-assisted software development. It provides structured guidelines, agent profiles, and best practices for building modern web applications with AI agents like Claude Code.

Key Features

• 📚 Complete Documentation Structure - Pre-built docs hierarchy with navigation index
• 🤖 AI Agent Profiles - 7 specialized agent roles (Frontend, Backend, Security, Testing, Code Review, Prompt Engineering, Documentation)
• 🎯 Product Archetypes - Pre-defined patterns for common product types (SaaS, Marketplace, Content Platform)
• 🏗️ Architecture Guidelines - Frontend (feature-first) and Backend (modular monolith) best practices
• 🔒 Security by Default - OWASP Top 10 compliance, security patterns, and audit checklists
• 💳 Payment Integration Patterns - Provider-agnostic payment flow design (Stripe, LiqPay, etc.)
• 📋 ADR Framework - Architecture Decision Records for tracking design decisions
• 🔄 Phase-Based Planning - 5-phase development methodology (Discovery → Support)
• 🌍 i18n Ready - Internationalization guidelines and structure
• 🐳 DevOps Templates - Docker, CI/CD, deployment checklists

Current Status

• 🚀 Phase 0 - Planning (Template Ready):
  • ✅ Complete documentation structure (/docs)
  • ✅ 7 AI agent profiles with detailed instructions
  • ✅ Frontend & Backend architecture guidelines
  • ✅ Security, API design, and payment flow patterns
  • ✅ ADR framework and templates
  • ✅ Development setup guidelines
  • ⏳ Ready for customization - Adapt to your project needs

---

Quick Start

Prerequisites

• Basic understanding of your project requirements
• Familiarity with AI-assisted development (Claude Code, GitHub Copilot, etc.)
• Your preferred tech stack (this template suggests Next.js + Node.js + PostgreSQL)

Getting Started

# 1. Clone or use this template
git clone <your-repo-url>
cd <your-project-name>

# 2. Review the product archetypes
cat docs/archetypes.md

# 3. Choose your archetype and fill project overview
# Edit: docs/project-overview.md

# 4. Plan your phases
# Edit: docs/phases-plan.md

# 5. Review agent profiles
ls -la agents/

# 6. Start development with AI agents
# Read: RULES.md for agent selection protocol

First Steps

1. Define Your Product

   • Read docs/archetypes.md
   • Choose archetype: SaaS Platform, Marketplace, Content Platform, or Custom
   • Select optional modules: Multi-tenancy, Payments, Analytics, etc.

2. Fill Project Overview

   • Edit docs/project-overview.md
   • Define goals, audience, tech stack, and key features

3. Plan Development Phases

   • Edit docs/phases-plan.md
   • Map features to phases (0-4)
   • Set milestones and success criteria

4. Configure AI Agents

   • Review RULES.md for agent selection protocol
   • Customize agent profiles in agents/ if needed
   • Start working with specialized agents

---

Tech Stack (Recommended)

Category	Technology
Frontend Framework	Next.js 15+ (App Router), React 19+
Language	TypeScript 5.x
Styling	Tailwind CSS 4.x, shadcn/ui
State Management	React Query / SWR + Zustand (optional)
Backend	Node.js + Express/Fastify
Database	PostgreSQL + Prisma/Drizzle ORM
Vector DB (AI)	pgvector (PostgreSQL extension)
Authentication	NextAuth.js v5 / Clerk
i18n	next-intl
Payments	Stripe / LiqPay / Fondy (provider-agnostic)
Email	Resend / SendGrid
File Storage	Vercel Blob / Cloudflare R2 / AWS S3
Deployment	Vercel / Docker + VPS

Note: This is a suggested stack. Adapt to your project needs - the documentation structure works with any modern web stack.

---

Project Structure

your-project/
├── .github/                       # GitHub templates
│   ├── ISSUE_TEMPLATE/            # Issue templates (bug, feature)
│   └── PULL_REQUEST_TEMPLATE.md   # PR template
├── docs/                          # Complete documentation
│   ├── archetypes.md              # Product archetypes & optional modules
│   ├── project-overview.md        # Project overview template
│   ├── phases-plan.md             # Phase-based development plan
│   ├── content-structure.md       # Content/page structure
│   ├── dev-setup.md               # Development setup guide
│   ├── adr/                       # Architecture Decision Records
│   │   ├── README.md              # ADR guidelines
│   │   └── 0000-template.md       # ADR template
│   ├── frontend/                  # Frontend documentation
│   │   ├── overview.md            # Frontend overview
│   │   ├── architecture.md        # Feature-first architecture
│   │   ├── ui-ux-guidelines.md    # UX/UI best practices
│   │   └── seo-performance.md     # SEO & performance
│   ├── backend/                   # Backend documentation
│   │   ├── overview.md            # Backend overview
│   │   ├── architecture.md        # Modular monolith architecture
│   │   ├── api-design.md          # API design principles
│   │   ├── security.md            # Security patterns
│   │   └── payment-flow.md        # Payment integration
│   ├── llm/                       # AI/LLM system documentation
│   │   ├── prompting.md           # Prompt structure & versioning
│   │   ├── evals.md               # Evaluation strategy & datasets
│   │   ├── safety.md              # Safety, privacy, injection defense
│   │   ├── caching-costs.md       # Token caching & budget optimization
│   │   └── rag-embeddings.md      # RAG design & evaluation
│   └── examples/                  # Filled-in examples
│       └── RECOMMENDATIONS-example.md
├── agents/                        # AI agent profiles
│   ├── frontend-architect.md      # Frontend agent profile
│   ├── backend-architect.md       # Backend agent profile
│   ├── security-auditor.md        # Security agent profile
│   ├── test-engineer.md           # Testing agent profile
│   ├── code-reviewer.md           # Code review agent profile
│   ├── prompt-engineer.md         # Prompt engineering agent
│   └── documentation-expert.md   # Documentation specialist
├── apps/                          # Application code (Phase 2+)
│   ├── web/                       # Frontend app (Next.js)
│   └── api/                       # Backend API (Node.js)
├── packages/                      # Shared packages (if monorepo)
│   └── shared/                    # Types, utils, API client
├── .claude/                        # Claude Code configuration
│   ├── settings.json              # Hooks configuration
│   ├── hooks/                     # Hook scripts
│   │   ├── protect-files.sh       # Block edits to sensitive files
│   │   ├── bash-firewall.sh       # Block dangerous commands
│   │   ├── post-edit-format.sh    # Auto-format after edits
│   │   └── audit-log.sh           # Log all Bash commands
│   └── skills/                    # Slash-command skills (14 total)
├── .editorconfig                  # Editor formatting standards
├── .env.example                   # Environment variables template
├── package.json                   # Project metadata & engines
├── DOCS.md                        # Documentation index
├── RULES.md                       # Project rules & agent protocol
├── RECOMMENDATIONS.md             # Project-specific decisions
└── README.md                      # This file

---

Documentation

📚 Full Documentation Index - Complete documentation map

Core Documentation

Planning & Architecture:

• Product Archetypes 🎯 - Choose your product pattern
• Project Overview 📋 - Project definition template
• Phases Plan 🗓️ - 5-phase development methodology
• Content Structure 📄 - Page/content organization
• ADR Framework 📝 - Architecture Decision Records

Frontend:

• Frontend Overview - Frontend stack overview
• Architecture - Feature-first architecture pattern
• UI/UX Guidelines - Design system principles
• SEO & Performance - Optimization strategies

Backend:

• Backend Overview - Backend stack overview
• Architecture - Modular monolith pattern
• API Design - RESTful/GraphQL best practices
• Security - OWASP Top 10, auth patterns
• Payment Flow - Provider-agnostic payment design

AI Agents:

• RULES.md - Agent selection protocol and project rules
• Frontend Architect - Frontend specialist agent
• Backend Architect - Backend specialist agent
• Security Auditor - Security review agent
• Test Engineer - Testing specialist agent
• Code Reviewer - Code quality agent
• Prompt Engineer - AI prompt specialist
• Documentation Expert - Technical writing & docs maintenance

---

Development Phases

This template follows a 5-phase methodology. Adapt to your project timeline:

Phase 0 - Discovery & Requirements (1-2 weeks)

• Define product vision, goals, and target audience
• Choose product archetype and optional modules
• Select tech stack and tools
• Document requirements and constraints
• Set up initial project structure

Phase 1 - Architecture & Design (2-3 weeks)

• Design system architecture (frontend + backend)
• Define API contracts and data models
• Create database schema
• Plan authentication and authorization
• Document architecture decisions (ADRs)
• Set up development environment

Phase 2 - MVP Implementation (4-8 weeks)

• Implement core user flows
• Build essential UI/UX components
• Set up authentication and user management
• Integrate third-party services (payments, email, etc.)
• Implement basic admin features
• Set up monitoring and logging

Phase 3 - Improvements & Scaling (3-4 weeks)

• Improve code quality and test coverage
• Optimize performance (frontend + backend)
• Conduct security audit and fixes
• Enhance observability (logs, metrics, traces)
• Implement advanced features
• Prepare for production deployment

Phase 4 - Support & Evolution (Ongoing)

• Production deployment and monitoring
• Bug fixes and maintenance
• Feature iterations based on user feedback
• Scaling infrastructure as needed
• Documentation updates
• Continuous improvement

Total estimated time: 10-17 weeks (single developer) or 6-10 weeks (2-3 developers)

See docs/phases-plan.md for detailed phase breakdown.

---

How to Use This Template

For New Projects

1. Clone/Fork this repository

   git clone <your-repo-url>
   cd <your-project-name>
   

2. Choose Your Archetype

   • Read docs/archetypes.md
   • Identify your product type (SaaS, Marketplace, Content, Custom)
   • Select optional modules (Multi-tenancy, Payments, Analytics, etc.)

3. Fill Project Documentation

   • Edit docs/project-overview.md - define your product
   • Edit docs/phases-plan.md - plan your roadmap
   • Edit docs/content-structure.md - define pages/features

4. Customize Agent Profiles

   • Review RULES.md - understand agent selection protocol
   • Review agent profiles in agents/
   • Customize profiles if needed (add project-specific context)

5. Start Development

   • Use specialized agents for different tasks
   • Document decisions in docs/adr/
   • Keep documentation updated as you build

For Existing Projects

1. Adopt Documentation Structure

   • Copy relevant docs from docs/ to your project
   • Adapt templates to match your current architecture
   • Document existing decisions as ADRs

2. Configure AI Agents

   • Copy RULES.md and agents/ to your project
   • Customize agent profiles with project-specific context
   • Train your team on agent selection protocol

3. Incremental Adoption

   • Start with one area (e.g., frontend architecture docs)
   • Gradually expand documentation coverage
   • Use agents for new features first, then refactor existing code

---

AI Agent Workflow

This template is optimized for AI-assisted development. Here's the recommended workflow:

1. Agent Selection Protocol

Before starting a task, select the appropriate agent based on RULES.md:

• Frontend tasks → frontend-architect.md
• Backend tasks → backend-architect.md
• Security review → security-auditor.md
• Testing → test-engineer.md
• Code review → code-reviewer.md
• AI/LLM integration → prompt-engineer.md
• Documentation → documentation-expert.md

2. Task Execution

Each agent profile includes:

• Role description - What this agent specializes in
• Responsibilities - What tasks to delegate
• Guidelines - How the agent should work
• Best practices - Domain-specific recommendations
• Checklist - Pre-flight checks before starting

3. Documentation Updates

• Document architecture decisions in docs/adr/
• Update relevant docs when making changes
• Keep phase plan current as you progress
• Use ADR template for significant decisions

---

Optional Modules

The template includes patterns for common modules. Keep only what you need:

Core Modules (Common to Most Projects)

• ✅ Authentication & Authorization
• ✅ User Management
• ✅ Database & ORM
• ✅ API Layer
• ✅ Email Notifications
• ✅ File Uploads

Optional Modules (Archetype-Specific)

• 💳 Payment Processing - Stripe, LiqPay, Fondy (SaaS, Marketplace)
• 🏢 Multi-tenancy - Organizations, teams, workspaces (SaaS B2B)
• 🤖 AI/LLM Integration - OpenAI, Anthropic, reasoning traces (AI Apps)
• 🔄 Background Jobs - Queue processing, scheduled tasks (Data Processing)
• 📊 Analytics & Events - Event logging, user tracking (Product Analytics)
• 🎥 Media Streaming - Video, audio, HLS (Content Platforms)
• 📱 Real-time Features - WebSockets, SSE (Collaboration Tools)
• 🌐 Multi-region - Geo-distributed deployments (Global SaaS)

See docs/archetypes.md for detailed module descriptions.

---

Best Practices

Documentation

• ✅ Write docs in English (international audience)
• ✅ Use Markdown for all documentation
• ✅ Keep docs close to code (docs/ folder)
• ✅ Update docs when making changes
• ✅ Use ADRs for architecture decisions

Code Organization

• ✅ Feature-first structure (frontend)
• ✅ Modular monolith (backend)
• ✅ Colocate tests with code
• ✅ Use TypeScript for type safety
• ✅ Follow single responsibility principle

Security

• ✅ OWASP Top 10 compliance
• ✅ Input validation (client + server)
• ✅ Rate limiting on sensitive endpoints
• ✅ Environment variable validation
• ✅ Regular security audits

AI Agent Usage

• ✅ Select appropriate agent for each task
• ✅ Provide context in agent prompts
• ✅ Review AI-generated code before committing
• ✅ Document AI-assisted decisions
• ✅ Iterate with feedback

See RECOMMENDATIONS.md for detailed best practices.

---

Example Use Cases

This template is designed for various product types:

SaaS Platforms

• Subscription-based services with billing
• Multi-tenant B2B applications
• Admin panels with RBAC

Marketplace Applications

• E-commerce platforms with vendor management
• Service marketplaces with booking systems
• Rental platforms with availability calendars

Content Platforms

• Blog/CMS systems with authoring workflows
• Media galleries with CDN integration
• Knowledge bases with search

AI-Powered Applications

• LLM integration with reasoning traces
• Document processing pipelines
• Intelligent automation tools

---

Contributing

Contributions are welcome! This template is designed to evolve with community feedback.

How to Contribute

1. Report Issues - Found a mistake or have a suggestion? Open an issue
2. Submit Improvements - Better docs, new agent profiles, or patterns? Open a PR
3. Share Use Cases - Used this template successfully? Share your story!

Contribution Guidelines

• Follow existing documentation style
• Update relevant sections when adding features
• Include examples and use cases
• Test with AI agents (Claude Code, GitHub Copilot)
• Keep language clear and concise

---

License

MIT

---

Support

Need help using this template?

• 📖 Read the full documentation
• 💡 Check best practices
• 🤔 Review agent profiles
• 🐛 Open an issue for bugs or questions
• 💬 Start a discussion for general questions

---

Acknowledgments

This template is designed for AI-assisted development with:

• Claude Code - Primary development assistant
• GitHub Copilot - Code completion
• Cursor - AI-first IDE

Inspired by best practices from Next.js, T3 Stack, and enterprise SaaS architectures.

---

Status: Phase 0 🚀 Template Ready - Ready for Customization Documentation: 📚 Complete (20+ guides) | AI Agents: 🤖 7 specialized profiles Architecture: ✅ Frontend (Feature-first) + Backend (Modular Monolith) Security: ✅ OWASP Top 10 patterns | Deployment: ✅ Docker + CI/CD templates