0.4.11
Поиск по документации… ⌘K
05 · Руководство пользователя

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

Как эффективно вести один проект через AstraCode — от первого запуска в репозитории до повторных сессий и долгих задач.

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

bash
cd ~/myproject
astracode

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

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

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

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

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

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

Если вы будете возвращаться к проекту регулярно, создайте AGENTS.md в корне репо. AstraCode читает его автоматически каждый раз.

Запустите:

text
/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. Сменить директорию посреди сессии

text
/cd ../other-project

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

После /cd AstraCode перечитает AGENTS.md нового проекта, обновит git-контекст.

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

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

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

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

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

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

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

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

Через модель

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

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

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

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

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

text
!cargo build
!git status
!ls -la

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

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

Когда модель предлагает изменение кода, она почти всегда использует apply_patch tool. Вы увидите diff, потом approval-диалог:

text
─────────────────────────────────────
  Tool wants to: apply patch
  ────────────────────────────────────
  *** Update File: src/auth.rs
  @@ -42,7 +42,7 @@
  -fn verify_token(t: &str) {
  +fn verify_token(t: &str) -> Result<()> {
       if t.is_empty() {
  -        panic!("empty token");
  +        return Err(Error::EmptyToken);
       }

  [y] allow once  [a] always  [p] prefix  [d] deny  [n] decline
─────────────────────────────────────

В версии 0.5.1 AstraCode перед каждой правкой через apply_patch или write_file сохраняет предыдущее состояние затронутых файлов. Если результат не подошёл, выполните /undo: откроется список записанных изменений с возможностью выбрать нужное. Для известного идентификатора вызова используйте /undo <call_id>.

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

Просмотрите diff. Если устраивает — y (разрешить один раз) или a (разрешать до конца сессии). Если нет — d (deny) и попросите изменить:

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

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

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

Sandbox по умолчанию не позволяет модели писать в: - .git/ — никогда. - .astracode/ — никогда. - .agents/ — никогда.

Это защита от случайной поломки. Если действительно нужно расширить права — измените writable_roots в ~/.astracode/config.toml или смените sandbox-режим (но не рекомендуется).

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

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

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

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

8. Git workflow

AstraCode хорошо умеет git:

text
Создай ветку feat/oauth, посмотри что я уже сделал в main, и обнови ветку.
text
Покажи git diff между HEAD и origin/main одним блоком.
text
Сделай коммит с текущими изменениями. Сообщение по conventional commits.

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

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

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

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

text
/index

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. 07-goals.md.

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

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

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

AstraCode сам предложит compact, когда близко к лимиту.

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

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

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

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

См. 09-side-conversations.md.

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

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

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

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

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

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

Плохо:

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

Хорошо:

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

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

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

text
/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.

В следующий раз AstraCode прочитает это в начале сессии.

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

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

Например:

text
/help goal
/help model
/help review

Откроется pager с описанием меню, USAGE, DETAILS и NOTES.

ESC