Модуль 2.6 · Урок 2

Урок 2: AGENTS.md — открытый стандарт

Практика

2.6 / Урок 2 из 5

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

Что такое AGENTS.md и почему это стандарт Linux Foundation
Структуру файла и назначение каждой секции
Как написать качественный AGENTS.md для своего проекта
Как инструменты (Codex, Claude Code, Gemini) используют этот файл

Что такое AGENTS.md?

AGENTS.md — это открытый стандарт для инструктирования AI-агентов о вашем проекте.

Стандарт: Agentic AI Foundation (Linux Foundation), с 2025
Формат: Markdown
Расположение: корень проекта или поддиректории
Поддержка (60,000+ open-source проектов к 2025):
   [+] OpenAI Codex
   [+] Claude Code / Claude Projects
   [+] Gemini CLI
   [+] GitHub Copilot
   [+] Cursor IDE
   [+] Amp, Devin, Factory, Jules, VS Code и другие

Почему стандарт?

graph LR
    A["Разработчик<br/>пишет AGENTS.md"] --> B["Один файл"]
    B --> C["Все инструменты<br/>понимают"]
    C --> D["[+] Консистентность"]
    C --> E["[+] Переносимость"]
    C --> F["[+] Не надо писать<br/>5 разных файлов"]

    style A fill:#e1f5ff
    style B fill:#c8e6c9
    style D fill:#fff9c4
    style E fill:#fff9c4
    style F fill:#fff9c4

Структура AGENTS.md

Файл состоит из следующих основных секций:

# Project overview

# Development conventions

# Testing

# Build & deploy

# Architecture

# Do's and Don'ts

Рассмотрим каждую подробно.

Секция 1: Project overview

Назначение: дать агенту общее представление о проекте.

Что включать:

## Project overview

### What this project does
Краткое описание проекта (2-3 предложения).

### Technology stack
Список основных технологий:
- Runtime: Node.js 18+
- Framework: Express 4.18
- Database: PostgreSQL 14
- ORM: Prisma 3.15
- Package manager: npm 9+

### Purpose
Кому нужен этот проект и для чего.

### Key libraries & tools
- express: Web framework
- prisma: Database ORM
- jest: Testing
- eslint: Code linting

Пример (реально):

## Project overview

### What this project does
RESTful API для управления задачами и проектами. Позволяет пользователям
создавать задачи, расставлять приоритеты, отслеживать статус и
сотрудничать в командах.

### Technology stack
- Runtime: Node.js 18+
- Framework: Express 4.18
- Database: PostgreSQL 14
- ORM: Prisma 3.15
- Language: TypeScript 5.0
- Testing: Jest 29
- Package manager: npm 9+

### Purpose
Внутренний инструмент для команды разработки. Используется web-интерфейсом
и мобильным приложением.

### Key libraries & tools
- express: REST API routing
- prisma: Type-safe database ORM
- jest: Unit and integration testing
- supertest: HTTP testing
- typescript: Static typing
- eslint: Code linting
- prettier: Code formatting

Секция 2: Development conventions

Назначение: описать, как пишется код в этом проекте.

Что включать:

## Development conventions

### Code style
Описание стиля кодирования.

### Naming conventions
Как именовать переменные, функции, классы.

### File structure
Как организованы файлы.

### Imports
Правила для импортов.

### Error handling
Как обрабатывать ошибки.

Пример для Python Django проекта:

## Development conventions

### Code style
- Language: Python 3.11+
- Formatter: Black (line length: 88)
- Linter: pylint
- Type checker: mypy
- Pre-commit hooks: enabled

### Naming conventions
- Functions and variables: `snake_case`
- Classes: `PascalCase`
- Constants: `UPPER_SNAKE_CASE`
- Private methods/attributes: prefix with `_`
- Django models: plural names (e.g., `Users`, `Tasks`)

### File structure

project/ ├── users/ │ ├── models.py # Django models │ ├── views.py # Views/endpoints │ ├── serializers.py # DRF serializers │ ├── tests.py # Tests │ └── urls.py # URL routing ├── tasks/ │ └── [same structure] ├── settings.py # Django settings └── manage.py


### Imports
- Use `from x import y` when possible
- Avoid `import *`
- Group imports: stdlib → third-party → local
- Relative imports only within same app

### Error handling
- Use Django REST Framework exceptions
- Return meaningful HTTP status codes
- Always include error message in response body
- Log errors with proper level (warning, error, critical)

Example:
```python
from rest_framework.exceptions import ValidationError

if not valid:
    raise ValidationError("User email already exists")


## Секция 3: Testing

**Назначение:** объяснить, как тестируется код.

**Что включать:**

```markdown
## Testing

### Test framework
Какой фреймворк используется.

### Running tests
Команды для запуска.

### Test coverage
Требуемое покрытие.

### Testing conventions
Как писать тесты.

Пример:

## Testing

### Test framework
- Framework: Jest 29
- Language: TypeScript
- Assertion library: jest built-in

### Running tests
```bash
# Run all tests
npm test

# Run specific test file
npm test -- src/__tests__/users.test.ts

# Run with coverage
npm test -- --coverage

# Watch mode
npm test -- --watch

Test coverage

Minimum coverage: 80%
Critical paths: 90%+
Generated code exempted (e.g., Prisma)

Testing conventions

Test file location: src/__tests__/ or .test.ts next to source
Test naming: describe('functionName', () => { ... })
One assertion per test when possible
Use factory functions for test data (not hardcoded)
Mock external APIs (HTTP, databases)
Don’t make real network requests in tests

Example structure:

describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid email', () => {
      // Arrange
      const userData = { email: 'test@example.com', name: 'John' };

      // Act
      const result = userService.createUser(userData);

      // Assert
      expect(result).toHaveProperty('id');
    });
  });
});


## Секция 4: Build & deploy

**Назначение:** объяснить, как собирается и развёртывается проект.

**Что включать:**

```markdown
## Build & deploy

### Building the project
Команды сборки.

### Environment variables
Требуемые переменные окружения.

### Deployment
Как развёртывается в разные окружения.

Пример:

## Build & deploy

### Building the project
```bash
# Development build
npm run dev

# Production build
npm run build

# Output: dist/ directory

Dependencies:

Node 18+ required
npm ci for clean installs
No global dependencies

Environment variables

Create .env.local with:

DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
JWT_SECRET=your-secret-key
REDIS_URL=redis://localhost:6379
NODE_ENV=development

Copy .env.example as template.

Deployment

Development:

npm run dev    # Runs on http://localhost:3000

Staging:

npm run build
npm start      # Production server
# Deployed to staging.example.com

Production:

Use Docker: docker build -t app . && docker run app
Migrations run automatically on startup
Requires all env vars set
Health check: GET /health returns 200


## Секция 5: Architecture

**Назначение:** объяснить высокоуровневую архитектуру проекта.

**Что включать:**

```markdown
## Architecture

### Project structure
Диаграмма структуры файлов.

### Module descriptions
Что делает каждый модуль.

### Data flow
Как данные движутся через систему.

Пример для веб-приложения:

## Architecture

### Project structure

src/ ├── controllers/ # HTTP request handlers ├── services/ # Business logic (reusable) ├── models/ # Data models & schemas ├── middleware/ # Express middleware ├── utils/ # Helper functions ├── types/ # TypeScript types ├── database/ # Database connections └── tests/ # Test files


### Module descriptions
- **controllers/**: Handle HTTP requests, call services, return responses
- **services/**: Core business logic, independent of HTTP/DB specifics
- **models/**: Prisma schemas and types
- **middleware/**: Authentication, logging, error handling
- **utils/**: Reusable helpers (date formatting, validation, etc.)
- **database/**: Connection pooling, migrations

### Data flow

HTTP Request ↓ Express Router ↓ Controller (parse request) ↓ Service (business logic) ↓ Database/External API ↓ Service (format response) ↓ Controller (status code) ↓ HTTP Response


### Key design patterns
- Separation of concerns: Controllers → Services → Models
- Middleware for cross-cutting concerns
- No business logic in controllers
- Services are testable without HTTP

Секция 6: Do’s and Don’ts

Назначение: запретить антипаттерны и неправильные подходы.

Структура:

## Do's and Don'ts

### DO:
- List of good practices

### DON'T:
- List of anti-patterns

Пример:

## Do's and Don'ts

### DO:
[+] Use async/await for asynchronous code
[+] Handle all errors explicitly
[+] Log at appropriate levels (info, warn, error)
[+] Use environment variables for configuration
[+] Write tests for critical paths
[+] Use TypeScript types consistently
[+] Keep services focused on single responsibility
[+] Use parameterized queries (Prisma does this)

### DON'T:
[-] DON'T write business logic in controllers
[-] DON'T use `any` types without explanation
[-] DON'T make synchronous external API calls
[-] DON'T log sensitive data (passwords, tokens)
[-] DON'T hardcode values (use env vars)
[-] DON'T modify database without migrations
[-] DON'T skip error handling with try-catch
[-] DON'T commit `.env` files
[-] DON'T use console.log (use logger)
[-] DON'T create long-running tasks in request handlers

### Common mistakes
1. **Mixing concerns:** calling database directly from controller
   ```typescript
   // [-] Wrong
   app.post('/users', (req, res) => {
     const user = await db.users.create(req.body);
     res.json(user);
   });

   // [+] Right
   app.post('/users', (req, res) => {
     const user = await userService.createUser(req.body);
     res.json(user);
   });

Forgetting error handling:

// [-] Wrong
const user = await userService.create(data);

// [+] Right
try {
  const user = await userService.create(data);
} catch (error) {
  logger.error('Failed to create user', error);
  res.status(400).json({ error: error.message });
}


<Callout type="info" title="Обязательные разделы AGENTS.md">
Качественный AGENTS.md должен содержать пять ключевых разделов: **Архитектура** (структура проекта и модулей), **Стек** (технологии и версии), **Структура** (расположение файлов и папок), **Соглашения** (правила именования и стиля кода), **Команды** (как запускать, тестировать и деплоить).
</Callout>

## Полный пример AGENTS.md для Python Flask API

```markdown
# AGENTS.md

## Project overview

### What this project does
REST API for e-commerce platform. Handles products, orders, payments, and user accounts.

### Technology stack
- Runtime: Python 3.11+
- Framework: Flask 3.0
- Database: PostgreSQL 15
- ORM: SQLAlchemy 2.0
- Package manager: pip + requirements.txt
- Testing: pytest
- API docs: OpenAPI/Swagger

### Purpose
Backend for web and mobile clients. Processes orders, manages inventory,
handles payments via Stripe integration.

### Key libraries & tools
- flask: Web framework
- sqlalchemy: Database ORM
- marshmallow: Serialization
- pytest: Testing
- python-dotenv: Environment variables
- flask-cors: CORS support
- stripe: Payment processing

---

## Development conventions

### Code style
- Language: Python 3.11+
- Formatter: Black (line length: 88)
- Linter: pylint, flake8
- Type checker: mypy
- Pre-commit: enabled

### Naming conventions
- Functions and variables: `snake_case`
- Classes: `PascalCase`
- Database models: `PascalCase`
- API endpoints: `/lowercase-with-dashes`
- Private methods: prefix with `_`

### File structure

app/ ├── routes/ # API endpoints ├── models/ # SQLAlchemy models ├── schemas/ # Marshmallow serializers ├── services/ # Business logic ├── utils/ # Helper functions ├── tests/ │ ├── test_routes.py │ ├── test_models.py │ └── test_services.py ├── config.py # Configuration └── app.py # Flask app factory


### Imports
- Group: stdlib → third-party → local
- Use relative imports: `from . import utils`
- Avoid `from module import *`

### Error handling
```python
from werkzeug.exceptions import BadRequest

try:
    user = get_user(user_id)
except UserNotFound:
    raise BadRequest("User not found")

Testing

Test framework

pytest 7+
pytest-flask for Flask integration
pytest-cov for coverage

Running tests

# All tests
pytest

# Specific file
pytest tests/test_routes.py

# With coverage
pytest --cov=app

# Verbose
pytest -v

Test coverage

Minimum: 80%
Routes: 90%+
Services: 85%+

Testing conventions

Test file naming: test_*.py
Test functions: test_*
Use fixtures for setup
One assertion per test when possible

Build & deploy

Building

No build step. Run directly with Flask development server.

# Development
flask run    # http://localhost:5000

# Production: gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 app:app

Environment variables

DATABASE_URL=postgresql://user:pass@localhost/dbname
FLASK_ENV=development
SECRET_KEY=your-secret-key
STRIPE_API_KEY=sk_live_...
REDIS_URL=redis://localhost:6379

Deployment

Docker: docker build -t api . && docker run api
Migrations: flask db upgrade
Health check: GET /health returns 200

Architecture

Data flow

HTTP Request
    ↓
Flask Route (validates input)
    ↓
Service (business logic)
    ↓
SQLAlchemy Model (database)
    ↓
Service (format response)
    ↓
Schema (serialization)
    ↓
JSON Response

Key components

routes/: Define endpoints
services/: Reusable business logic
models/: Database models
schemas/: Request/response validation

Do’s and Don’ts

DO:

[+] Use services for business logic [+] Validate input in routes [+] Log errors with traceback [+] Use environment variables [+] Write tests for critical paths [+] Use type hints (Python 3.10+) [+] Handle database errors gracefully

DON’T:

[-] Write logic directly in routes [-] Hardcode configuration [-] Log sensitive data (passwords, API keys) [-] Skip validation [-] Use db.session.commit() without error handling [-] Create long-running tasks in request handlers


## Практика: создание AGENTS.md для своего проекта

### Чек-лист для написания:

- [ ] Заполнена секция "Project overview"
- [ ] Описаны технологии в "Technology stack"
- [ ] Документированы соглашения кодирования
- [ ] Объяснено, как запустить тесты
- [ ] Указаны команды build и deploy
- [ ] Описана архитектура проекта
- [ ] Перечислены Do's and Don'ts
- [ ] Добавлены примеры кода где нужно
- [ ] Файл расположен в корне проекта

### Размер файла

Рекомендуемый размер: **300-500 строк**

- Слишком короткий (&lt;100 строк): агенту недостаточно информации
- Слишком длинный (>1000 строк): теряется в деталях, не вся информация нужна

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

Выберите свой проект и напишите AGENTS.md, используя структуру выше.

**Минимум для начала:**

```markdown
# AGENTS.md

## Project overview

[Your project description]
[Technology stack]

## Development conventions

[Code style rules]
[Naming conventions]

## Testing

[How to run tests]

## Build & deploy

[Build commands]

## Do's and Don'ts

[5-10 ключевых правил]

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

AGENTS.md — универсальный стандарт для всех AI-инструментов (OpenAI Codex, Claude Code, Gemini CLI, Cursor, GitHub Copilot и 60,000+ проектов). Управляется Agentic AI Foundation (Linux Foundation) с 2025 года.
6 основных секций:
- Project overview (общее описание)
- Development conventions (как писать код)
- Testing (как тестировать)
- Build & deploy (как собирать и развёртывать)
- Architecture (структура проекта)
- Do’s and Don’ts (запреты и правила)
Размер: 300-500 строк — достаточно информации, но не перегружено деталями.
Примеры в файле критичны: агент лучше учится на примерах, чем на описаниях.
Один файл для всех: нет нужды создавать CLAUDE.md, GEMINI.md отдельно, если хороший AGENTS.md.

Следующий урок

Урок 3: CLAUDE.md — специфика для Claude

Узнаете:

Чем CLAUDE.md отличается от AGENTS.md
Оптимальный размер и структуру
Иерархию файлов (корень, поддиректории, глобальный)
Как итеративно улучшать CLAUDE.md на основе ошибок агента

Урок 2: AGENTS.md — открытый стандарт

AGENTS.md и документация

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

Что такое AGENTS.md?

Почему стандарт?

Структура AGENTS.md

Секция 1: Project overview

Секция 2: Development conventions

Test coverage

Testing conventions

Environment variables

Deployment

Секция 6: Do’s and Don’ts

Testing

Test framework

Running tests

Test coverage

Testing conventions

Build & deploy

Building

Environment variables

Deployment

Architecture

Data flow

Key components

Do’s and Don’ts

DO:

DON’T:

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

Следующий урок

// Обсуждение