mirror of
https://github.com/Ku6epXBOCTuK/easy-png-tools.git
synced 2026-11-13 17:08:20 +00:00
76 lines
5.8 KiB
Markdown
76 lines
5.8 KiB
Markdown
# Документация проекта
|
||
|
||
> Статус: **active**. Это индекс документов и карта источников истины для
|
||
> разработчиков и агентов. Подробные правила находятся в самих документах, а
|
||
> обязательный краткий контракт — в `AGENTS.md`.
|
||
|
||
## Порядок чтения
|
||
|
||
1. `AGENTS.md` — команды, обязательные инварианты и границы old/new.
|
||
2. Этот файл — выбрать актуальный документ по теме.
|
||
3. `docs/plan-codebase-quality.md` — текущий план приведения качества в порядок
|
||
и последовательность следующих шагов.
|
||
4. Соответствующий план или checklist темы.
|
||
5. Исходники, конфигурация и тесты рядом с изменяемым кодом.
|
||
|
||
## Активные документы
|
||
|
||
| Документ | Роль | Статус |
|
||
| ---------------------------------- | ---------------------------------------------------- | ------ |
|
||
| `AGENTS.md` | Краткий обязательный контракт для агента | active |
|
||
| `docs/plan-codebase-quality.md` | План quality gates, тестов и lint-правил | draft |
|
||
| `docs/agent-workflow.md` | Подробный порядок исследования, изменения и проверки | active |
|
||
| `docs/quality-gates.md` | Команды проверки, warnings и CI | active |
|
||
| `docs/backlog.md` | Продуктовые, UX- и инфраструктурные задачи | active |
|
||
| `docs/roadmap.md` | Общие направления развития | active |
|
||
| `docs/plan-redesign.md` | Новый дизайн и границы `/v1` | active |
|
||
| `docs/plan-preview-i18n.md` | План i18n нового UI | active |
|
||
| `docs/plan-seo.md` | SEO/GEO-план | active |
|
||
| `docs/plan-platform.md` | PWA/API/WASM-план | active |
|
||
| `docs/checklist-manual-testing.md` | Ручная приёмка preview | active |
|
||
| `docs/tools-map.md` | Живая карта инструментов | active |
|
||
| `web/eslint-plugins/README.md` | Детали custom lint rules и token policy | active |
|
||
| `docs/archive/README.md` | Правила архивирования и удаления старых документов | active |
|
||
|
||
`docs/archive/` содержит временную историческую справку и не является текущим
|
||
источником критериев приёмки. Для старых документов действует срок хранения 30
|
||
дней; после него их удаляют, а при необходимости достают из git history.
|
||
|
||
## Где хранить новую информацию
|
||
|
||
- Поведение, которое агент обязан соблюдать сразу, — кратко в `AGENTS.md`.
|
||
- Точные команды, параметры скриптов и критерии качества — в
|
||
`docs/quality-gates.md` или в README соответствующей подсистемы.
|
||
- Архитектура, потоки данных и границы модулей — в отдельном architecture-плане
|
||
или документе, не дублируя существующие планы.
|
||
- Реализация lint-правил, fixtures и технические детали ESLint — в
|
||
`web/eslint-plugins/README.md` и исходниках правил.
|
||
- Продуктовые решения и ручная приёмка — в backlog, плане и checklist.
|
||
|
||
Подробные материалы хранятся в `docs/`, а не в корне. Новый файл создаётся
|
||
только если темы нет в существующем документе; иначе обновляется источник
|
||
истины.
|
||
|
||
## Текущий baseline Q0
|
||
|
||
На момент фиксации Q0:
|
||
|
||
- registry нового UI содержит 122 инструмента;
|
||
- `pnpm --dir web check` проходит без ошибок и предупреждений;
|
||
- `pnpm --dir web lint:all` завершается с 0 errors, но с 188 warnings
|
||
`i18n/dict-consistency` и 4 unused design tokens;
|
||
- unit/e2e результаты считать актуальными только после отдельного прогона;
|
||
исторические числа в `docs/archive/` не являются baseline.
|
||
|
||
Baseline и следующий шаг поддерживаются в `docs/plan-codebase-quality.md`.
|
||
|
||
## Правила актуальности
|
||
|
||
- У активного документа есть статус: `draft`, `active`, `completed` или
|
||
`archived`.
|
||
- Ссылки на конкретный файл или команду проверяются при изменении источника
|
||
истины.
|
||
- Архивный документ не возвращается в live-критерии без явной сверки.
|
||
- После каждого шага плана агент останавливается, показывает изменённые файлы,
|
||
проверки и нерешённые решения, и ждёт ревью.
|