490 lines
19 KiB
Markdown
490 lines
19 KiB
Markdown
# 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.
|
|
|
|
[](./DOCS.md)
|
|
[](./docs/phases-plan.md)
|
|
[](./agents/)
|
|
[](./LICENSE)
|
|
|
|
---
|
|
|
|
## 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** - 6 specialized agent roles (Frontend, Backend, Security, Testing, Code Review, Prompt Engineering)
|
|
- 🎯 **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`)
|
|
- ✅ 6 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
|
|
|
|
```bash
|
|
# 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`](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`](docs/project-overview.md)
|
|
- Define goals, audience, tech stack, and key features
|
|
|
|
3. **Plan Development Phases**
|
|
- Edit [`docs/phases-plan.md`](docs/phases-plan.md)
|
|
- Map features to phases (0-4)
|
|
- Set milestones and success criteria
|
|
|
|
4. **Configure AI Agents**
|
|
- Review [`RULES.md`](RULES.md) for agent selection protocol
|
|
- Customize agent profiles in [`agents/`](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
|
|
├── 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](./DOCS.md)** - Complete documentation map
|
|
|
|
### Core Documentation
|
|
|
|
**Planning & Architecture:**
|
|
- **[Product Archetypes](./docs/archetypes.md)** 🎯 - Choose your product pattern
|
|
- **[Project Overview](./docs/project-overview.md)** 📋 - Project definition template
|
|
- **[Phases Plan](./docs/phases-plan.md)** 🗓️ - 5-phase development methodology
|
|
- **[Content Structure](./docs/content-structure.md)** 📄 - Page/content organization
|
|
- **[ADR Framework](./docs/adr/README.md)** 📝 - Architecture Decision Records
|
|
|
|
**Frontend:**
|
|
- **[Frontend Overview](./docs/frontend/overview.md)** - Frontend stack overview
|
|
- **[Architecture](./docs/frontend/architecture.md)** - Feature-first architecture pattern
|
|
- **[UI/UX Guidelines](./docs/frontend/ui-ux-guidelines.md)** - Design system principles
|
|
- **[SEO & Performance](./docs/frontend/seo-performance.md)** - Optimization strategies
|
|
|
|
**Backend:**
|
|
- **[Backend Overview](./docs/backend/overview.md)** - Backend stack overview
|
|
- **[Architecture](./docs/backend/architecture.md)** - Modular monolith pattern
|
|
- **[API Design](./docs/backend/api-design.md)** - RESTful/GraphQL best practices
|
|
- **[Security](./docs/backend/security.md)** - OWASP Top 10, auth patterns
|
|
- **[Payment Flow](./docs/backend/payment-flow.md)** - Provider-agnostic payment design
|
|
|
|
**AI Agents:**
|
|
- **[RULES.md](./RULES.md)** - Agent selection protocol and project rules
|
|
- **[Frontend Architect](./agents/frontend-architect.md)** - Frontend specialist agent
|
|
- **[Backend Architect](./agents/backend-architect.md)** - Backend specialist agent
|
|
- **[Security Auditor](./agents/security-auditor.md)** - Security review agent
|
|
- **[Test Engineer](./agents/test-engineer.md)** - Testing specialist agent
|
|
- **[Code Reviewer](./agents/code-reviewer.md)** - Code quality agent
|
|
- **[Prompt Engineer](./agents/prompt-engineer.md)** - AI prompt specialist
|
|
|
|
---
|
|
|
|
## 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`](docs/phases-plan.md) for detailed phase breakdown.
|
|
|
|
---
|
|
|
|
## How to Use This Template
|
|
|
|
### For New Projects
|
|
|
|
1. **Clone/Fork this repository**
|
|
```bash
|
|
git clone <your-repo-url>
|
|
cd <your-project-name>
|
|
```
|
|
|
|
2. **Choose Your Archetype**
|
|
- Read [`docs/archetypes.md`](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`](docs/project-overview.md) - define your product
|
|
- Edit [`docs/phases-plan.md`](docs/phases-plan.md) - plan your roadmap
|
|
- Edit [`docs/content-structure.md`](docs/content-structure.md) - define pages/features
|
|
|
|
4. **Customize Agent Profiles**
|
|
- Review [`RULES.md`](RULES.md) - understand agent selection protocol
|
|
- Review agent profiles in [`agents/`](agents/)
|
|
- Customize profiles if needed (add project-specific context)
|
|
|
|
5. **Start Development**
|
|
- Use specialized agents for different tasks
|
|
- Document decisions in [`docs/adr/`](docs/adr/)
|
|
- Keep documentation updated as you build
|
|
|
|
### For Existing Projects
|
|
|
|
1. **Adopt Documentation Structure**
|
|
- Copy relevant docs from [`docs/`](docs/) to your project
|
|
- Adapt templates to match your current architecture
|
|
- Document existing decisions as ADRs
|
|
|
|
2. **Configure AI Agents**
|
|
- Copy [`RULES.md`](RULES.md) and [`agents/`](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`](RULES.md):
|
|
|
|
- **Frontend tasks** → [`frontend-architect.md`](agents/frontend-architect.md)
|
|
- **Backend tasks** → [`backend-architect.md`](agents/backend-architect.md)
|
|
- **Security review** → [`security-auditor.md`](agents/security-auditor.md)
|
|
- **Testing** → [`test-engineer.md`](agents/test-engineer.md)
|
|
- **Code review** → [`code-reviewer.md`](agents/code-reviewer.md)
|
|
- **AI/LLM integration** → [`prompt-engineer.md`](agents/prompt-engineer.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/`](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`](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`](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](./LICENSE)
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
Need help using this template?
|
|
|
|
- 📖 Read the [full documentation](./DOCS.md)
|
|
- 💡 Check [best practices](./RECOMMENDATIONS.md)
|
|
- 🤔 Review [agent profiles](./agents/)
|
|
- 🐛 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](https://claude.ai/claude-code)** - Primary development assistant
|
|
- **[GitHub Copilot](https://github.com/features/copilot)** - Code completion
|
|
- **[Cursor](https://cursor.sh/)** - 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:** 🤖 6 specialized profiles
|
|
**Architecture:** ✅ Frontend (Feature-first) + Backend (Modular Monolith)
|
|
**Security:** ✅ OWASP Top 10 patterns | **Deployment:** ✅ Docker + CI/CD templates |