Save this content to: AGENTS.md

# AGENTS.md

> Карта проекта для AI agents и разработчиков. Обновляйте её при существенном изменении структуры или AI Factory контекста.

## Обзор проекта

`pepperfm/ssd-for-laravel` - PHP/Laravel package для простых DTO с typed properties, camelCase/snake_case mapping, attributes для явного mapping и iterable conversion.

## Tech Stack

- **Язык:** PHP 8.3+
- **Framework:** Laravel package, совместимость с Laravel 10.20+
- **Package manager:** Composer
- **Testing:** Pest 4, PHPUnit, Orchestra Testbench
- **Code style:** Laravel Pint, php-cs-fixer, StyleCI preset `laravel`
- **Database/ORM:** отсутствуют

## Структура проекта

```text
.
├── src/                       # Код Composer package под namespace Pepperfm\Ssd
│   ├── BaseDto.php            # Основное поведение DTO
│   ├── Attributes/            # MapName и ToIterable attributes
│   ├── Facades/               # Laravel facade
│   └── Providers/             # Laravel service provider
├── config/                    # Package config placeholder
├── tests/                     # Pest tests, fixtures и base TestCase
│   ├── Fixtures/              # DTO fixtures для тестов
│   └── Unit/                  # Unit scenarios для BaseDto creation
├── .github/workflows/         # GitHub Actions workflow
├── .ai-factory/               # AI Factory context, rules, architecture
└── .codex/                    # Project Codex config и skills
```

## Ключевые точки входа

| Файл | Назначение |
|---|---|
| `src/BaseDto.php` | Ядро DTO: нормализация входа, metadata cache, property assignment, serialization. |
| `src/Attributes/MapName.php` | Attribute для явного имени поля во входных/выходных данных. |
| `src/Attributes/ToIterable.php` | Attribute для преобразования iterable items во вложенные DTO/collection. |
| `src/Providers/SsdServiceProvider.php` | Laravel package integration и публикация config. |
| `composer.json` | Package metadata, autoload, dev tools, scripts. |
| `phpunit.xml.dist` | Конфигурация PHPUnit/Pest test suite. |
| `.github/workflows/main.yml` | CI workflow `run-tests`. |

## Документация

| Документ | Путь | Описание |
|---|---|---|
| README | `README.md` | Пользовательское описание установки и базового usage. |
| Changelog | `CHANGELOG.md` | История изменений package. |
| Contributing | `CONTRIBUTING.md` | Правила участия в разработке. |
| License | `LICENSE.md` | MIT license. |

## AI Context Files

| Файл | Назначение |
|---|---|
| `AGENTS.md` | Быстрая карта проекта для agents. |
| `.ai-factory/config.yaml` | Настройки AI Factory: язык, пути, git workflow. |
| `.ai-factory/DESCRIPTION.md` | Описание проекта, stack и функциональные границы. |
| `.ai-factory/ARCHITECTURE.md` | Архитектурные правила и dependency boundaries. |
| `.ai-factory/rules/base.md` | Базовые правила кодовой базы, определённые по текущему проекту. |

## Правила для агентов

- Не объединяйте несколько shell-команд в одну строку, если шаги имеют разный смысл или могут потребовать диагностики.
  - Неправильно: `git checkout master && git pull`
  - Правильно: сначала `git checkout master`, затем `git pull origin master`
- Не перетирайте пользовательские изменения. В текущем репозитории уже могут быть незакоммиченные правки.
- Для изменений поведения DTO запускайте самый узкий релевантный тест, обычно `composer test` или конкретный Pest-файл.
- Не добавляйте runtime side effects в `BaseDto`, attributes, provider или facade без явного требования.