Универсальный runbook нового Android-приложения

Этот документ нужен Codex перед созданием любого нового проекта в ~/projects/android. Сначала фиксируется пользовательский результат и данные, затем выбирается stack.

1. Паспорт приложения

Создайте отдельную папку и до генерации Android-проекта зафиксируйте:

Название:
Основной пользовательский сценарий:
Package ID:
Первый versionName/versionCode:
Телефон / tablet / foldable / Wear / TV / Auto / XR:
Native Compose / Capacitor / existing stack / engine:
Работает без сети: полностью / частично / нет:
Локальные данные:
Server/API и authentication:
Permissions и device capabilities:
Аккаунты, удаление аккаунта и данных:
Analytics / crash SDK / ads / billing:
Возрастная аудитория и чувствительная категория:
Google Play / RuStore / только internal:

Package ID, аудиторию, данные и permissions не угадывать. Если ответа пока нет, делайте безопасный локальный prototype без публикации и рискованных SDK.

2. Выбор implementation lane

Используйте матрицу stack:

• новый Android-first продукт → Kotlin/Compose;
• существующий web/PWA → Capacitor;
• network app → выбранный UI stack плюс data/repository contract;
• тяжёлая игра или специальный form factor → отдельное решение.

Codex записывает выбранный путь и причину в README/ADR. Не добавляйте Hilt, Room, Retrofit, Firebase, analytics или другой SDK до появления функции, которая действительно его требует.

3. Минимальная структура проекта

<app>/
├── AGENTS.md
├── README.md
├── android/ или native Gradle root
├── gradlew / gradle/wrapper/
├── scripts/
│   ├── doctor.sh
│   ├── verify.sh
│   └── device-smoke.sh
├── docs/
│   ├── architecture.md
│   └── play/
│       ├── privacy-policy.md
│       ├── data-safety.md
│       ├── content-rating.md
│       ├── policy-preflight.md
│       └── release-evidence.md
└── signing.properties.template

Native app обычно хранит settings.gradle.kts, root build.gradle.kts и app/. Capacitor app дополнительно хранит web source, lock-файл, capacitor.config.* и version-controlled android/.

4. Первый вертикальный сценарий

Реализуйте один законченный путь от запуска до наблюдаемого результата:

• Native local app: screen → state holder → repository/local source → UI.
• API client: loading → success → empty/error/offline → retry.
• Account app: login → authenticated state → logout; delete-account flow проектируется одновременно, если аккаунт можно создать.
• Device app: объяснение функции → contextual permission → success/denial.
• Capacitor: production web build → sync → native cold start.

Нельзя считать prototype завершённым, если happy path работает только с захардкоженными данными, а основные error/permission states отсутствуют.

5. Проектные команды

Каждый проект предоставляет одну полную проверку. Для native-проекта используйте проверенный Compose starter как исходную точку, а не как неизменяемый product template.

Native пример:

./gradlew lint test assembleDebug bundleRelease

Capacitor пример:

npm run lint
npm test
npm run build
npx cap sync android
cd android && ./gradlew lint test assembleDebug bundleRelease

UI/connected tests выбирают конкретный AVD/device и не используют молча первое случайное устройство.

6. Security и данные

• Backend/service-account secrets не попадают в APK или Git.
• Логи не содержат tokens, credentials, персональные данные и содержимое форм.
• Production endpoints используют TLS; debug trust overrides не попадают в release manifest.
• Экспортированные components, deep links, FileProvider и WebView проверяются.
• Данные минимизируются, retention/delete правила фиксируются до сбора.
• Каждый SDK заносится в inventory: назначение, permissions, данные, destinations, Data Safety и способ удаления.

7. UX и lifecycle

• Clean install и cold/warm start.
• Основная пользовательская задача.
• Back, Home, background/resume и process recreation.
• Rotation/resize, phone/tablet и accessibility font scale.
• Keyboard/focus/screen reader для релевантных экранов.
• Dark/light themes и edge-to-edge/safe areas.
• Offline, timeout, server error и expired session по фактическому продукту.
• Permission denial, «не спрашивать снова» и системное revoke.
• Upgrade с предыдущей версией без потери данных.

8. Google Play preflight

До подключения рекламы, login, billing, UGC, health/finance/news/VPN, background location или sensitive API откройте Google Play policy preflight. Policy влияет на архитектуру; откладывать этот анализ до готового AAB поздно.

9. Definition of Done

• [ ] Паспорт и stack записаны, package ID подтверждён.
• [ ] Реальный основной сценарий закончен, включая ошибки/отказ.
• [ ] Gradle Wrapper и зависимости воспроизводимы.
• [ ] Unit/lint/build и релевантные UI/contract tests проходят.
• [ ] APK/AAB собраны, package/version/permissions и SHA-256 проверены.
• [ ] Clean install и lifecycle smoke пройдены на AVD/device.
• [ ] Privacy/Data Safety/content/audience/ads declarations соответствуют коду.
• [ ] Store listing показывает текущую сборку и не обещает лишнего.
• [ ] Signing, Play-delivered build и owner gates отделены от локальной сборки.
• [ ] Итоговый diff не содержит secrets, local SDK paths, caches или binaries.

Готовый запрос Codex

Используй $android-release. Создай в ~/projects/android отдельное
Android-приложение <название>. Основной сценарий: <сценарий>. Сначала заполни
паспорт из docs/30-development/new-app-runbook.md и выбери stack по
docs/10-architecture/stack-selection.md. Package ID <id> не менять. Не
добавляй permissions, SDK, рекламу, аналитику или сбор данных без явной
необходимости и Google Play policy review. Реализуй полный вертикальный
сценарий, тесты и project-local verify; собери APK/AAB и пройди AVD smoke.
В финале раздели изменённое, проверенное и owner/Play Console gates.