Структура-ориентированная кодовая база для AI-агента: как организовать файлы и автоматизировать справку

Почему ваш AI-агент тупит в вашем же коде?

Вы даете агенту задачу: "добавь авторизацию в этот микросервис". Он начинает рыскать по файлам, тратит 80% контекста на чтение импортов и поиск точек входа. А через 10 минут выдает код, который ломает сборку. Знакомо? Проблема не в модели (даже GPT-5 на 03.03.2026 не всесильна), а в хаосе, который вы называете проектом.

Решение – структура-ориентированная кодовая база. Не просто папки, а система, где расположение и имя файла говорят о его роли громче, чем его содержимое. Где агент не гадает, а точно знает, куда идти.

1 Придумайте структуру, которую поймет даже пьяный студент (или сонный агент)

Забудьте про плоские списки из 50 файлов в src/. Мозг агента (да и ваш) ищет паттерны. Создайте иерархию, основанную на бизнес-доменах или архитектурных слоях.

# ПЛОХО. Агент в панике.
project/
├── auth.py
├── db.py
├── api.py
├── utils.py
└── main.py

# ХОРОШО. Агент уже догадывается.
project/
├── core/           # Бизнес-логика, независимая от внешнего мира
│   ├── auth/
│   │   ├── service.py
│   │   └── models.py
│   └── payments/
├── infrastructure/ # Подключение к миру
│   ├── database/
│   ├── api/
│   └── message_broker/
└── application/    # Точки входа (CLI, HTTP-роуты)
    ├── cli.py
    └── web.py

2 Именуйте файлы так, чтобы их можно было найти по смыслу

file.py – это не имя. Это оскорбление. Имя файла должно быть самодокументируемым и следовать жесткому правилу: тип_назначение.расширение.

Агент ищет не глазами, а семантическим поиском. Когда вы просите "найди сервис для работы с платежами", он будет сканировать имена файлов на совпадение с "service" и "payment". Дайте ему эту возможность.

3 Пишите комментарии для агентов, а не для себя

Ваш комментарий # Складываем A и B перед строкой c = a + b бесполезен. Агент видит код. Ему нужно объяснить зачем и контекст, который не виден в синтаксисе.

# ПЛОХО. Шум.
def calculate_price(quantity, price):
    # Возвращает общую стоимость
    return quantity * price

# ХОРОШО. Контекст для агента.
def calculate_price(quantity: int, price: float) -> float:
    """
    Рассчитывает итоговую стоимость позиции заказа БЕЗ учета НДС.
    Используется в модуле формирования счетов (core/invoicing/).
    ВАЖНО: Метод не проверяет наличие товара на складе. Эту проверку
    выполняет calling функция `validate_order()` перед вызовом.
    """
    return quantity * price

Такой комментарий – готовый кусок для навыка агента. Он понимает границы ответственности функции и знает, что нельзя просто взять и вставить ее в другое место без валидации.

4 Создайте AGENTS.md – карту местности для вашего агента

Это главный файл. Не README.md для людей, а навигационный щит для ИИ. Располагайте его в корне. Его цель – за 30 секунд дать агенту полную картину проекта.

# AGENTS.md – Карта проекта "Платежный шлюз"

## Назначение проекта
Микросервис для приема онлайн-платежей через провайдеров X и Y.

## Живые точки входа (с чего начать работу)
- `application/web.py:app` – FastAPI приложение. Все HTTP-запросы идут сюда.
- `application/cli.py` – Команды для администрирования (сброс кэша, повторение платежей).

## Архитектурные слои (от внешнего к внутреннему)
1.  `application/` – Адаптеры. Трансформируют внешние запросы (HTTP, CLI) во внутренние команды.
2.  `core/` – Ядро с бизнес-правилами. НЕ ЗАВИСИТ от внешних библиотек и фреймворков.
    - `core/payments/` – Логика проведения платежа, валидация.
    - `core/auth/` – Внутренняя авторизация действий.
3.  `infrastructure/` — Реализация портов из ядра для работы с БД, провайдерами, кэшем.

## Критические зависимости (что ломается чаще всего)
- Файл `infrastructure/payment_providers/x_gateway.py` — интеграция с провайдером X. При изменении API провайдера менять здесь.
- База данных: схема описана в `infrastructure/database/models.py`. Миграции в `/migrations/`.

## Где что искать (шаблоны путей)
- Все сервисы бизнес-логики: `core/*/service_*.py`
- Все модели данных (Pydantic, dataclass): `core/*/models.py`
- Все интеграции с внешними API: `infrastructure/*_gateway.py` или `infrastructure/*_client.py`

## Частые задачи и их решения
- "Добавить новый платежный метод":
    1.  Добавить константу в `core/payments/constants.py`.
    2.  Реализовать класс провайдера в `infrastructure/payment_providers/`.
    3.  Зарегистрировать провайдер в `infrastructure/payment_providers/__init__.py`.

5 Автоматизируйте обновление AGENTS.md. Иначе он умрет через неделю

Ручное ведение документации – путь в никуда. Напишите скрипт, который проходит по src/**/*, анализирует структуру и коммиты, и генерирует свежий AGENTS.md. Запускайте его в pre-commit hook или по расписанию в CI.

#!/usr/bin/env python3
"""
generate_agents_md.py - Автоматическая генерация AGENTS.md на 03.2026.
Сканирует проект, находит точки входа, анализирует импорты для построения графа зависимостей.
"""

import os
import ast
from pathlib import Path
from typing import Dict, List

def get_project_structure(root: Path) -> Dict[str, List[str]]:
    """Рекурсивно собирает структуру каталогов и файлов."""
    structure = {}
    for item in root.rglob('*'):
        if item.is_file() and '__pycache__' not in str(item):
            rel_path = item.relative_to(root)
            parent = str(rel_path.parent)
            structure.setdefault(parent, []).append(rel_path.name)
    return structure

def find_entry_points(root: Path) -> List[str]:
    """Ищет файлы, которые выглядят как точки входа (содержат 'app', 'main', 'run')."""
    entry_points = []
    for file in root.rglob('*.py'):
        content = file.read_text(encoding='utf-8')
        if 'if __name__ == "__main__"' in content or 'app = FastAPI()' in content:
            entry_points.append(str(file.relative_to(root)))
    return entry_points[:5]  # Ограничиваем топ-5

def generate_md_content(structure: Dict, entries: List[str], root: Path) -> str:
    """Генерирует содержимое AGENTS.md."""
    md_lines = ["# AGENTS.md - Автоматически сгенерированная карта проекта\n"]
    md_lines.append(f"Сгенерировано: {__import__('datetime').datetime.now().isoformat()}\n")

    md_lines.append("## Живые точки входа")
    for ep in entries:
        md_lines.append(f"- `{ep}`")

    md_lines.append("\n## Структура проекта")
    for dir_name, files in sorted(structure.items()):
        if dir_name == '.':
            continue
        md_lines.append(f"\n### `{dir_name}/`")
        for f in sorted(files)[:10]:  # Показываем первые 10 файлов
            md_lines.append(f"- `{f}`")

    return '\n'.join(md_lines)

if __name__ == '__main__':
    project_root = Path('.')
    struct = get_project_structure(project_root)
    entry_pts = find_entry_points(project_root)
    md_content = generate_md_content(struct, entry_pts, project_root)

    output_file = project_root / 'AGENTS.md'
    output_file.write_text(md_content, encoding='utf-8')
    print(f"[+] AGENTS.md обновлен. Точек входа найдено: {len(entry_pts)}")

Это базовый скелет. В реальности его нужно доработать: добавить парсинг docstring для извлечения назначений модулей, анализ requirements.txt для раздела "Зависимости", может, даже интеграцию с GitHub Copilot для предложения "Частых задач". Но даже этот скрипт спасет AGENTS.md от забвения.

6 Интегрируйте документацию в рабочий процесс. Сделайте ее обязательной

Добавьте проверку в ваш CI/CD пайплайн: если скрипт генерации AGENTS.md обнаружил изменения в структуре (появилась новая папка в `core/` или удалена точка входа), но сам AGENTS.md не обновлен – пайплайн падает. Жестко? Зато эффективно.

# .github/workflows/validate_agents_md.yml
name: Validate AGENTS.md

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Генерируем свежий AGENTS.md
        run: python scripts/generate_agents_md.py
      - name: Проверяем, изменился ли AGENTS.md
        run: |
          if git diff --name-only HEAD | grep -q "^AGENTS.md$"; then
            echo "AGENTS.md был изменен вручную. Проверьте актуальность генератора."
          else
            echo "AGENTS.md актуален."
          fi
      # Можно добавить проверку, что файл не пустой и содержит ключевые разделы

Типичные провалы (и как их не повторить)

• AGENTS.md становится музеем. Решение – та самая автоматизация. Скрипт должен запускаться при каждом коммите, меняющем структуру. Используйте git hooks или CI.
• Слишком много деталей. AGENTS.md – это карта, а не энциклопедия. Не перечисляйте каждую функцию. Указывайте модули, их назначение и связи. Детали агент найдет сам, когда придет в нужный файл.
• Игнорирование истории. Агент может работать эффективнее, если понимает эволюцию кода. Добавьте в AGENTS.md раздел "Исторические решения": почему выбрали провайдера X, а не Y, или почему отказались от кэширования в определенном модуле. Это сэкономит ему массу времени на анализ мертвого кода.

Итог простой. Вы либо тратите время один раз, чтобы навести порядок и научить агента в нем ориентироваться. Либо тратите время каждый день, исправляя его глупые ошибки, вызванные непониманием вашего же кода. Выбор за вами.

P.S. Неочевидный совет на 2026 год: скоро появятся специализированные LLM, обученные исключительно на чтении и анализе кодовых баз (что-то вроде CodeBERT, но для архитектуры). Готовьте почву уже сейчас. Ваш хорошо структурированный проект с живым AGENTS.md станет для них идеальным полигоном, и они отплатят вам скоростью и точностью, недоступной сегодняшним моделям общего назначения.

Подписаться на канал