Expand README.md with a comprehensive project overview, detailed documentation structure, phase-based development methodology, AI agent workflow, recommended tech stack, and modular best practices to enhance clarity and usability for AI-assisted project development.
This commit is contained in:
olekhondera
485
README.md
485
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) — стартовый шаблон (наполните деталями под ваш проект).
|
[](./DOCS.md)
|
||||||
|
[](./docs/phases-plan.md)
|
||||||
|
[](./agents/)
|
||||||
|
[](./LICENSE)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Что входит в шаблон
|
## Project Overview
|
||||||
- Базовая структура документации (`/docs`) и индекс навигации.
|
|
||||||
- Папка `agents/` с примерами профилей агентов разных ролей (frontend/backend/security/test/code‑review/prompt‑engineer) и общими правилами (`RULES.md`).
|
**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.
|
||||||
- Рекомендации по архитектуре фронтенда/бэкенда, безопасности, API‑дизайну и оплатам (провайдер‑агностично).
|
|
||||||
- Примеры модулей и практик (опционально): мультиарендность, интеграции/ингест, очереди фоновых задач, event‑лог, explainability (`reasoning_trace`), биллинг — **оставляйте только то, что нужно вашему продукту**.
|
### Key Features
|
||||||
- Предложенный стек: Next.js (TypeScript, Tailwind, React Query/SWR) на фронте; Node.js + Express/Fastify, Prisma/Drizzle, Postgres (+опц. `pgvector`) на бэкенде; Docker для деплоя.
|
|
||||||
|
- 📚 **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
|
||||||
- **Phase 0 — Discovery & Requirements:** зафиксируйте цели/аудиторию, требования и стек.
|
|
||||||
- **Phase 1 — Architecture & Design:** детализируйте архитектуру, API, схемы данных, очереди/события.
|
### Prerequisites
|
||||||
- **Phase 2 — MVP Implementation:** реализуйте ключевые потоки, UI/UX, интеграции, биллинг (если нужен).
|
|
||||||
- **Phase 3 — Improvements & Scaling:** качество, производительность, безопасность, наблюдаемость.
|
- Basic understanding of your project requirements
|
||||||
- **Phase 4 — Support & Evolution:** поддержка, релизы, эволюция фич.
|
- 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)
|
||||||
- **Общие документы (`/docs`):**
|
|
||||||
[`docs/archetypes.md`](docs/archetypes.md) — продуктовые архетипы и опциональные модули;
|
| Category | Technology |
|
||||||
[`docs/project-overview.md`](docs/project-overview.md) — обзор проекта (шаблон);
|
|----------|-----------|
|
||||||
[`docs/phases-plan.md`](docs/phases-plan.md) — план по фазам;
|
| **Frontend Framework** | Next.js 15+ (App Router), React 19+ |
|
||||||
[`docs/content-structure.md`](docs/content-structure.md) — структура контента/страниц.
|
| **Language** | TypeScript 5.x |
|
||||||
[`docs/adr/README.md`](docs/adr/README.md) — как фиксировать архитектурные решения (ADR);
|
| **Styling** | Tailwind CSS 4.x, shadcn/ui |
|
||||||
[`docs/dev-setup.md`](docs/dev-setup.md) — dev‑setup и команды (когда появится код).
|
| **State Management** | React Query / SWR + Zustand (optional) |
|
||||||
- **Frontend (`/docs/frontend`)** — обзор, архитектура (feature‑first), UX/UI гайды, SEO/performance.
|
| **Backend** | Node.js + Express/Fastify |
|
||||||
- **Backend (`/docs/backend`)** — обзор, архитектура (модульный монолит), API design, security, payment flow (провайдер‑агностично), события и вебхуки.
|
| **Database** | PostgreSQL + Prisma/Drizzle ORM |
|
||||||
- **Индексы/правила:** [`DOCS.md`](DOCS.md) — индекс документации; [`RULES.md`](RULES.md) и папка [`agents/`](agents/) — правила и профили агентов.
|
| **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
|
||||||
- **Быстрый старт:** начните с `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`).
|
your-project/
|
||||||
- **Внесение изменений:** обновляйте документы при принятии решений; для новых подсистем добавляйте файлы в `docs/` (предпочтительно — английский).
|
├── 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 <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
|
||||||
|
|
||||||
|
**Last Updated:** 2025-12-17
|
||||||
|
|||||||
Reference in New Issue
Block a user