05. Работа с проектом

Как эффективно вести один проект через Астра ИИ [КОД] — от первого запуска в репозитории до повторных сессий и долгих задач.

1. Старт в новом проекте

cd ~/myproject
astracode

Астра ИИ [КОД] видит: - Где вы находитесь (cwd). - В Git ли это репозиторий (показывает ветку). - Какие файлы есть (по запросу — через list_dir).

Что важно для первого хода

Полезно сразу дать модели контекст:

Это проект на Rust, бэкенд для платёжной системы. Тесты — cargo test --workspace.
Главный модуль — src/payments. Сейчас занимаюсь рефакторингом auth.

Чем больше контекста — тем точнее ответы. Особенно — нестандартные команды, конвенции, текущая задача.

2. AGENTS.md — постоянный контекст проекта

Если вы будете возвращаться к проекту регулярно, создайте AGENTS.md в корне репо. Астра ИИ [КОД] читает его автоматически каждый раз.

Запустите:

/init

/init просит модель собрать скелет файла: обзор, как собрать, как тестировать, стиль кода. Просмотрите и подправьте. Если AGENTS.md уже существует — команда ничего не перезапишет, а лишь сообщит, что файл уже на месте.

Хороший AGENTS.md содержит

• О проекте: что это, какие технологии.
• Как сборка: npm install && npm run build, cargo build --release, make...
• Как тесты: какой раннер, нужны ли preconditions.
• Стиль кода: rustfmt? prettier? специфичные правила.
• Коммиты: conventional commits? squash перед merge?
• «Don'ts»: чего никогда не делать в этом проекте.

Что НЕ нужно в AGENTS.md

• Архитектура целиком — модель прочитает код, если ей понадобится.
• Подробности интеграций — лучше в отдельных файлах под docs/.
• Секреты и креды — никогда.

3. Сменить директорию

/cd ../other-project

Tab — авто-дополнение подкаталогов. Повторный Tab — спуститься на уровень.

После /cd Астра ИИ [КОД] перечитает AGENTS.md нового проекта, обновит git-контекст.

Песочница не переключается автоматически — если в новом проекте нужно расширить writable_roots, проверьте /status или поправьте ~/.astracode/config.toml.

4. Упоминать файлы в промпте

Вместо «отрефактори файл auth.rs» используйте @:

Отрефактори @src/auth.rs так, чтобы verify_token возвращал Result вместо panic.

Это сигнал модели: «вот конкретный файл, начни с него». В поле ввода @ открывает окно выбора файла — введите часть имени, выберите.

Можно указать несколько:

В @src/auth.rs функция verify_token использует константу из @src/config.rs. 
Перенеси её в @src/auth/constants.rs.

5. Запуск shell-команд

Через модель

Просто скажите, что хотите выполнить:

Запусти cargo test --package myapp -- --nocapture

Модель сама выберет инструмент (exec_command / shell), покажет результат, прокомментирует.

Напрямую (без модели)

Если хотите быстро что-то сделать руками, не «тратя» токены:

!cargo build
!git status
!ls -la

Префикс ! — выполнить shell-команду из поля ввода. Песочница и подтверждения применяются так же.

6. Применение патчей

Когда модель предлагает изменение кода, она почти всегда использует инструмент apply_patch. Правка отображается в блоке вызова инструмента. Если ей нужны права за пределами текущей политики песочницы, появится диалог подтверждения:

  Внести следующие изменения?

  Причина: <причина эскалации, если есть>

› 1. Да, продолжить (y)
  2. Да, и больше не спрашивать для этих файлов (a)
  3. Нет, и сказать Астра ИИ [КОД], что сделать иначе (esc)

  Press enter to confirm or esc to cancel

Астра ИИ [КОД] перед каждой правкой через apply_patch или write_file сохраняет предыдущее состояние затронутых файлов. Если результат не подошёл:

• /undo — отменяет последнее записанное изменение;
• /undo file <путь> [--force] — отменяет все изменения файла за последний завершённый ход;
• /undo call <call_id> [--force] — отменяет конкретный сохранённый вызов инструмента, даже из более раннего хода.

Без --force конфликт (файл менялся снаружи или уже новее записи) прерывает отмену, не трогая файл. Результат самой отмены тоже можно откатить повторным /undo.

Undo восстанавливает только файловую правку агента. Оно не отменяет произвольные shell-команды, операции во внешних системах или уже отправленный git push; redo пока нет.

Если появился диалог подтверждения, просмотрите изменения и причину эскалации. Если действие устраивает — y (разрешить один раз) или a (разрешать аналогичные действия до конца сессии). Если нет — d (deny) и попросите изменить:

Не панику, а Err — но ошибка должна быть с контекстом. Используй anyhow::bail.

Полный набор клавиш диалога подтверждения: y — allow once, a — allow always (for session), p — approve for prefix, d — deny, n/Esc — decline, o — открыть тред, c — cancel. Подробно — 13-safety.md.

Защищённые пути

Стандартная restricted-политика workspace-write исключает из записи служебные директории верхнего уровня .git/, .astracode/ и .agents/. Это защита от случайной поломки, но не безусловная hard-гарантия: явное правило записи может её переопределить, а в danger-full-access песочница полностью отключена.

Если действительно нужно расширить права, сначала разберитесь, какой конкретно путь требуется действию. Предпочитайте узкое правило более широкому режиму песочницы.

7. Использование тестов как обратной связи

Лучший способ убедить модель не ошибаться — заставить её прогонять тесты:

Реализуй фичу X. После каждого изменения запускай cargo test --workspace. 
Если падает — сначала разберись, потом продолжай.

Модель будет цикл «изменить → запустить → починить» делать сама. Если падают тесты, она увидит stacktrace и поправит.

8. Git workflow

Астра ИИ [КОД] хорошо умеет git:

Создай ветку feat/oauth, посмотри что я уже сделал в main, и обнови ветку.

Покажи git diff между HEAD и origin/main одним блоком.

Сделай коммит с текущими изменениями. Сообщение по conventional commits.

⚠️ Никогда не push'ит без явного разрешения. Force-push требует ваше явное «да».

/diff даёт полноэкранный просмотр со всеми текущими изменениями — удобнее, чем читать в чате.

9. Индекс проекта (/index)

Если вы часто работаете в большом репозитории, можно построить индекс модулей — Obsidian-style vault, который Астра ИИ [КОД] использует для навигации:

/index

У команды есть подкоманды: build (построить индекс), status (проверить состояние), clear (удалить). Индекс хранится в ~/.astracode/projects/<hash от пути>/ — отдельно для каждого проекта и не попадает в сам репозиторий.

На большом проекте /index build сначала считает объём работы и показывает оценку — сколько узлов, AI-вызовов и примерно токенов потребуется — не запускаясь сразу:

Для индекса выбрано N узлов: M AI-вызовов, K из кэша, примерно Xk входных токенов. Запуск может занять заметное время и стоить денег. Для запуска повторите: /index build --force.

Построение расходует токены (платно), поэтому на небольших проектах подтверждение не требуется, а на больших нужно явно повторить команду с --force.

10. Несколько проектов параллельно

Если работаете в нескольких репозиториях:

Вариант 1 — отдельные TUI:

# Терминал 1
cd ~/projectA
astracode

# Терминал 2
cd ~/projectB
astracode

Каждый — своя сессия, своя история, общие настройки.

Вариант 2 — /cd внутри одной сессии:

/cd ~/projectA
... сделать там что-то ...

/cd ~/projectB
... сделать там что-то ...

Контекст один. Модель будет помнить, что недавно работала в А.

Вариант 3 — tmux + /sessions: - Закрываете TUI в одном проекте. - Открываете в другом. - /sessions показывает обе сессии — переключайтесь как угодно. (/resume — алиас для /sessions, на случай muscle-memory.)

11. Долгая задача — /goal

Если задача займёт час или несколько сессий — задайте цель:

/goal Добавить OAuth-логин через Google. Соответствует ADR-042. Бюджет — 300k токенов.

После этого, что бы вы ни делали — модель помнит про цель. После /new или перезапуска — /sessions восстановит контекст.

См. 07-goals.md.

12. Когда контекст переполняется

Каждое сообщение тратит токены. При длинной сессии видите в строке состояния 45.0k / 50.0k tokens — близко к лимиту.

Что делать: - /compact — модель сожмёт старые ходы в резюме, освободит место. - /new — начать сначала (потеряет нюансы текущего разговора, но контекст с проектом всё равно есть в AGENTS.md). - /fork — копия сессии для экспериментов.

Астра ИИ [КОД] предложит compact, когда контекст будет близок к лимиту.

13. Side conversation — спросить, не отвлекаясь

Посреди длинной задачи вы хотите уточнить что-то — но не загрязнять основной разговор:

/side как работает Rc<RefCell<T>> по сравнению с Arc<Mutex<T>>?

Откроется временный sub-разговор. Закончили — Esc, вернётесь в main. Главный ход не «увидит» этот вопрос.

См. 09-side-conversations.md.

14. Подключение к большим контекстам через MCP

Если работаете с задачами в Linear/Jira, переписками в Slack, кодом в GitHub PRs — подключите MCP-сервер:

# ~/.astracode/config.toml
[mcp_servers.linear]
command = "npx"
args = ["-y", "@linear/mcp-server"]
env_vars = ["LINEAR_API_KEY"]

После рестарта /mcp покажет, что Linear доступен, и модель сможет сама смотреть тикеты, создавать комментарии и т.п. См. 11-mcp.md.

15. Подсказки по эффективности

Делайте задачу узкой

Плохо:

Перепиши auth с нуля как считаешь нужным.

Хорошо:

В @src/auth.rs verify_token использует unwrap. Замени на ? и убедись, что 
все вызывающие функции корректно обрабатывают Err.

Просите план перед действием

Для крупного — /plan:

/plan Мигрировать auth с JWT на OAuth2 (использовать crate oauth2 0.5)

Модель сначала напишет план — посмотрите, скорректируйте, дайте go.

Используйте /review перед коммитом

Привычка: перед git commit запустить /review. Поймаете много мелких косяков ещё до тестов.

Учите модель «своему стилю»

В AGENTS.md явно: «Используем anyhow::Result, не custom Error enum». «Тесты с cargo nextest run, не cargo test». «PR title в conventional commits».

Сохраняйте успешные паттерны

Если разговор привёл к хорошему результату — сделайте резюме в AGENTS.md или docs/:

Подключение OAuth2 — см. docs/oauth-setup.md.

В следующий раз Астра ИИ [КОД] прочитает это в начале сессии.

16. Не забывайте про /help

Если забыли команду или хотите узнать про функцию — /help. Каждая страница имеет EN/RU версии.

Например:

/help goal
/help model
/help review

Откроется полноэкранный просмотр с описанием меню, USAGE, DETAILS и NOTES.