diff --git a/README.md b/README.md index 10f0e8e..7c2494c 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,468 @@ -# Универсальный стартовый шаблон документации ИИ агентов (AI) +# 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. -**Текущий статус:** Phase 0 (Planning) — стартовый шаблон (наполните деталями под ваш проект). +[![Documentation](https://img.shields.io/badge/docs-comprehensive-blue)](./DOCS.md) +[![Phase](https://img.shields.io/badge/phase-0%20planning-yellow)](./docs/phases-plan.md) +[![AI Ready](https://img.shields.io/badge/AI-ready-green)](./agents/) +[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE) --- -## Что входит в шаблон -- Базовая структура документации (`/docs`) и индекс навигации. -- Папка `agents/` с примерами профилей агентов разных ролей (frontend/backend/security/test/code‑review/prompt‑engineer) и общими правилами (`RULES.md`). -- Рекомендации по архитектуре фронтенда/бэкенда, безопасности, API‑дизайну и оплатам (провайдер‑агностично). -- Примеры модулей и практик (опционально): мультиарендность, интеграции/ингест, очереди фоновых задач, event‑лог, explainability (`reasoning_trace`), биллинг — **оставляйте только то, что нужно вашему продукту**. -- Предложенный стек: Next.js (TypeScript, Tailwind, React Query/SWR) на фронте; Node.js + Express/Fastify, Prisma/Drizzle, Postgres (+опц. `pgvector`) на бэкенде; Docker для деплоя. +## 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 --- -## Фазы (как основа для планирования) -- **Phase 0 — Discovery & Requirements:** зафиксируйте цели/аудиторию, требования и стек. -- **Phase 1 — Architecture & Design:** детализируйте архитектуру, API, схемы данных, очереди/события. -- **Phase 2 — MVP Implementation:** реализуйте ключевые потоки, UI/UX, интеграции, биллинг (если нужен). -- **Phase 3 — Improvements & Scaling:** качество, производительность, безопасность, наблюдаемость. -- **Phase 4 — Support & Evolution:** поддержка, релизы, эволюция фич. +## 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 +cd + +# 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 --- -## Навигация по документации -- **Общие документы (`/docs`):** - [`docs/archetypes.md`](docs/archetypes.md) — продуктовые архетипы и опциональные модули; - [`docs/project-overview.md`](docs/project-overview.md) — обзор проекта (шаблон); - [`docs/phases-plan.md`](docs/phases-plan.md) — план по фазам; - [`docs/content-structure.md`](docs/content-structure.md) — структура контента/страниц. - [`docs/adr/README.md`](docs/adr/README.md) — как фиксировать архитектурные решения (ADR); - [`docs/dev-setup.md`](docs/dev-setup.md) — dev‑setup и команды (когда появится код). -- **Frontend (`/docs/frontend`)** — обзор, архитектура (feature‑first), UX/UI гайды, SEO/performance. -- **Backend (`/docs/backend`)** — обзор, архитектура (модульный монолит), API design, security, payment flow (провайдер‑агностично), события и вебхуки. -- **Индексы/правила:** [`DOCS.md`](DOCS.md) — индекс документации; [`RULES.md`](RULES.md) и папка [`agents/`](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. --- -## Как использовать шаблон -- **Быстрый старт:** начните с `docs/archetypes.md`, выберите архетип и набор модулей, затем заполните `docs/project-overview.md` и `docs/phases-plan.md`. -- **Технический дизайн:** используйте `docs/frontend/architecture.md` и `docs/backend/architecture.md`; для API и безопасности — `docs/backend/api-design.md` и `docs/backend/security.md`; оплаты — `docs/backend/payment-flow.md` (как пример/рыбу). -- **Работа с агентами:** перед задачей проверяйте `RULES.md`; агент выбирается по описанию профилей в `agents/` (см. протокол выбора в `RULES.md`). -- **Внесение изменений:** обновляйте документы при принятии решений; для новых подсистем добавляйте файлы в `docs/` (предпочтительно — английский). +## Project Structure + +``` +your-project/ +├── 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 +│ ├── frontend/ # Frontend documentation +│ │ ├── overview.md # Frontend overview +│ │ ├── architecture.md # Feature-first architecture +│ │ ├── ui-ux-guidelines.md # UX/UI best practices +│ │ ├── internationalization.md# i18n setup +│ │ └── 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 +│ └── events-webhooks.md # Events & webhooks +├── 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 +├── DOCS.md # Documentation index +├── RULES.md # Project rules & agent protocol +├── RECOMMENDATIONS.md # Best practices +└── 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 +- **[Internationalization](./docs/frontend/internationalization.md)** - i18n setup +- **[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 +- **[Events & Webhooks](./docs/backend/events-webhooks.md)** - Event-driven architecture + +**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 + cd + ``` + +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 + +**Last Updated:** 2025-12-17