Урок 5: Шаблоны для типовых проектов

Чему вы научитесь

• Использовать готовые шаблоны AGENTS.md и CLAUDE.md для типовых проектов
• Адаптировать шаблон под свой проект за 5 шагов
• Как тестировать документацию с AI-агентом
• Где найти больше примеров и шаблонов

4 готовых шаблона

Рассмотрим полные примеры для типовых проектов:

Шаблон 1: React Web App (Next.js + TypeScript)

AGENTS.md (укороченная версия):

# AGENTS.md

## Project overview

Next.js 16 web application for real-time task management.
Users can create projects, share with teams, track progress.

## Technology stack
- **Frontend:** Next.js 16, React 19, TypeScript 6+
- **Styling:** Tailwind CSS
- **State Management:** Zustand
- **Data Fetching:** TanStack Query
- **API Client:** axios
- **Testing:** Vitest, React Testing Library
- **Database:** PostgreSQL with Prisma
- **Node:** 20+ (рекомендуется 22 или 26)

## Development conventions

### Code style
- TypeScript strict mode
- Functional components with hooks only
- Tailwind CSS for styling
- No inline styles or CSS files

### Naming conventions
- Components: PascalCase (e.g., UserCard.tsx)
- Functions/variables: camelCase
- Files: match component name
- Constants: UPPER_SNAKE_CASE

### File structure

app/ ├── (auth)/ # Auth routes ├── (main)/ # App routes ├── api/ # API routes ├── components/ # React components ├── hooks/ # Custom hooks ├── store/ # Zustand stores ├── types/ # TypeScript types └── lib/ # Utilities

## Testing

```bash
npm test            # Run all tests
npm test -- --watch # Watch mode
npm test -- --coverage

Build & deploy

npm run dev         # Development: localhost:3000
npm run build       # Production build
npm start           # Run production build

Do’s and Don’ts

DO:

[+] Use TypeScript strictly [+] Handle errors explicitly [+] Write tests for critical paths [+] Use React Query for data fetching [+] Use Zustand for global state

DON’T:

[-] Don’t use class components [-] Don’t hardcode values [-] Don’t use inline styles [-] Don’t log sensitive data [-] Don’t skip error handling

**CLAUDE.md (краткая версия):**

```markdown
# CLAUDE.md

## Quick Summary

Next.js 14 + React 18 + TypeScript.
Styling: Tailwind. State: Zustand + React Query.
Testing: Vitest + React Testing Library.

## Key Rules

### DO:
- [+] Functional components with hooks
- [+] TypeScript strict mode
- [+] Tailwind CSS only
- [+] useQuery for data fetching
- [+] Error & loading states
- [+] Absolute imports: @/components

### DON'T:
- [-] No class components
- [-] No inline styles
- [-] No hardcoded values
- [-] No business logic in components
- [-] No console.log (use logger)

## Example Component

```typescript
'use client';

import { useQuery } from '@tanstack/react-query';
import { Button } from '@/components/ui';

export function TaskList() {
  const { data: tasks, isLoading, error } = useQuery({
    queryKey: ['tasks'],
    queryFn: () => fetch('/api/tasks').then(r => r.json()),
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div className="space-y-4">
      {tasks?.map(task => (
        <div key={task.id} className="p-4 border rounded">
          {task.title}
        </div>
      ))}
    </div>
  );
}

Commands

npm run dev      # Start development
npm test         # Run tests
npm run build    # Production build
npm run lint     # Check code

---

### Шаблон 2: FastAPI Backend (Python)

**AGENTS.md:**

```markdown
# AGENTS.md

## Project overview

REST API for e-commerce platform. Handles products, orders, payments.

## Technology stack
- **Backend:** Python 3.12+, FastAPI 0.136+
- **Database:** PostgreSQL 17 или 18, SQLAlchemy
- **Migrations:** Alembic
- **Testing:** pytest, pytest-asyncio
- **API Docs:** OpenAPI/Swagger
- **Package Manager:** pip + poetry

## Development conventions

### Code style
- Python 3.11+
- Formatter: Black (88 chars)
- Linter: pylint, flake8
- Type hints: required (mypy)

### Naming conventions
- Functions/variables: snake_case
- Classes: PascalCase
- API endpoints: /api/v1/lowercase-with-dashes
- Database models: PascalCase
- Constants: UPPER_SNAKE_CASE

### File structure

app/ ├── api/ │ ├── routes/ # API endpoints │ ├── models/ # SQLAlchemy models │ ├── schemas/ # Pydantic schemas │ └── services/ # Business logic ├── core/ │ ├── config.py │ ├── security.py │ └── logger.py ├── database/ ├── tests/ └── main.py

## Testing

```bash
pytest                  # All tests
pytest --cov=app       # With coverage
pytest tests/test_routes.py  # Specific file

Build & deploy

# Development
poetry run uvicorn app.main:app --reload

# Production
gunicorn -w 4 app:app

Do’s and Don’ts

DO:

[+] Use async/await [+] Validate with Pydantic [+] Use type hints [+] Handle errors explicitly

DON’T:

[-] Synchronous I/O [-] Hardcoded config [-] Log sensitive data [-] Skip validation

---

### Шаблон 3: Data Pipeline (Python)

```markdown
# AGENTS.md

## Project overview

ETL pipeline for data processing and analytics.
Ingests from multiple sources, transforms, loads to data warehouse.

## Technology stack
- **Language:** Python 3.12+
- **Data processing:** pandas, polars
- **Transformation:** dbt (data build tool)
- **Orchestration:** Airflow or Dagster
- **Storage:** PostgreSQL or Snowflake
- **Testing:** pytest, dbt tests
- **Validation:** Great Expectations

## Development conventions

### Code style
- Formatter: Black
- Linter: pylint
- Type hints: required (mypy)

### File structure

project/ ├── dbt/ │ ├── models/ │ │ ├── staging/ │ │ ├── intermediate/ │ │ └── marts/ │ ├── tests/ │ └── dbt_project.yml ├── scripts/ │ ├── extract.py │ ├── load.py │ └── validate.py ├── tests/ └── config/

## Do's and Don'ts

### DO:
[+] Version control all SQL
[+] Test data quality
[+] Document data lineage
[+] Use staging tables

### DON'T:
[-] Modify production tables directly
[-] Skip data validation
[-] Hardcode file paths
[-] Skip testing

Шаблон 4: Mobile App (React Native + Expo)

# AGENTS.md

## Project overview

Cross-platform mobile app (iOS & Android).
Built with React Native and Expo.

## Technology stack
- **Framework:** React Native, Expo
- **Language:** TypeScript
- **State:** Redux Toolkit or Zustand
- **Navigation:** React Navigation
- **Styling:** Tailwind CSS (NativeWind)
- **Testing:** Jest, Detox (e2e)
- **Package Manager:** npm

## Development conventions

### Code style
- TypeScript
- Formatter: Prettier
- Linter: ESLint

### File structure

app/ ├── src/ │ ├── screens/ │ ├── components/ │ ├── navigation/ │ ├── redux/ │ ├── services/ │ ├── types/ │ └── utils/ ├── assets/ ├── tests/ └── app.json

## Do's and Don'ts

### DO:
[+] Use functional components
[+] Handle permissions
[+] Test on real devices
[+] Optimize bundle size

### DON'T:
[-] Use class components
[-] Store secrets in AsyncStorage
[-] Hardcode API URLs
[-] Skip error boundaries

Как адаптировать шаблон за 5 шагов

Шаг 1: Скопируй нужный шаблон

Выбери тип своего проекта из 4 вариантов выше и скопируй его.

Шаг 2: Заполни основные данные

[YOUR_DESCRIPTION]         → Что делает твой проект?
[TARGET_USERS]             → Для кого это?
[KEY_FEATURE]              → Главные фичи

Шаг 3: Обнови Technology Stack

- Какие версии используешь?
- Какие дополнительные библиотеки?
- Какой package manager?

Шаг 4: Адаптируй соглашения кодирования

- Какой style guide?
- Какие правила именования?
- Какие инструменты линтирования?

Шаг 5: Добавь примеры из своего кода

Замени примеры на реальный код из твоего проекта. Это самая важная часть!

Практика: как тестировать документацию

Тест 1: С Claude Code

1. Скопируй CLAUDE.md в корень проекта
2. Открой Claude Code
3. Попроси: "Создай новый [feature]"
4. Оцени качество результата
   [+] Правильный стиль кода?
   [+] Правильная архитектура?
   [+] Правильные технологии?
5. Если ошибки → добавь правило в CLAUDE.md

Тест 2: Проверка полноты

- [ ] Все секции заполнены?
- [ ] Примеры соответствуют проекту?
- [ ] Команды работают?
- [ ] Версии актуальны?

Попробуйте сами

Быстрый вариант (30 минут)

1. Выбери тип своего проекта
2. Скопируй нужный шаблон
3. Заполни основные секции
4. Сохрани как AGENTS.md и CLAUDE.md

Полный вариант (2 часа)

1. Выбери тип проекта
2. Скопируй оба шаблона
3. Заполни все секции
4. Добавь примеры из своего кода
5. Попробуй работать с Claude Code
6. Улучши на основе результатов

Ключевые выводы

1. Готовые шаблоны ускоряют создание — не нужно писать с нуля.

2. 5-шаговая адаптация достаточна для большинства проектов.

3. Примеры из своего кода — самая важная часть.

4. Тестирование с Claude Code — лучший способ убедиться, что работает.

5. Начни с малого: даже 100 строк лучше ничего, расширяй потом.

Что дальше?

Создай документацию для своего проекта

1. Выбери тип проекта из 4 вариантов
2. Адаптируй шаблон за 5 шагов
3. Добавь примеры из своего кода
4. Проверь с Claude Code
5. Улучши на основе результатов

Делись с командой

git add AGENTS.md CLAUDE.md
git commit -m "Add AI documentation"
git push

Обновляй постепенно

После каждой ошибки Claude добавляй правило в CLAUDE.md.

Подведение итогов модуля

Чему ты научился

1. Урок 1: Зачем документировать проект для AI
2. Урок 2: AGENTS.md — открытый стандарт
3. Урок 3: CLAUDE.md — специфика для Claude
4. Урок 4: GEMINI.md и .cursorrules
5. Урок 5: Готовые шаблоны для типовых проектов

Следующие шаги

1. Создай AGENTS.md или CLAUDE.md для своего проекта
2. Испытай с Claude Code или другим инструментом
3. Улучши на основе результатов
4. Поделись с командой

Поздравляем! Ты завершил модуль 2.6.

Теперь ты знаешь, как документировать проекты для AI-агентов. Это улучшит качество результатов в 5+ раз и сэкономит часы работы.

Удачи!