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

AstraCode сам соберёт скелет файла: обзор, как собрать, как тестировать, стиль кода. Просмотрите и подправьте.

Хороший 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. (В Windows-сборке отдельный путь на чтение можно добавить через /sandbox-add-read-dir; на Linux/macOS этой команды нет.)

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
*** 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);
     }

Would you like to make the following edits?

› 1. Yes, proceed (y)
  2. Yes, and don't ask again for these files (a)
  3. No, and tell AstraCode what to do differently (esc)

Просмотрите diff. Если устраивает — y (или a, чтобы больше не спрашивать для этих файлов). Если нет — esc и попросите изменить:

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

Запись за пределами рабочей директории

В режиме workspace-write AstraCode, как правило, не пишет за пределами рабочей директории без подтверждения, а к служебным каталогам вроде .git/, .astracode/, .agents/ относится осторожно. Если запись действительно нужна — расширьте writable_roots в ~/.astracode/config.toml или смените sandbox-режим (не рекомендуется). В Windows-сборке отдельный путь на чтение добавляется через /sandbox-add-read-dir (на Linux/macOS этой команды нет).

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. Несколько проектов параллельно

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. 07-goals.md.

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

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

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

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

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

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

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

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

См. 09-side-conversations.md.

13. Подключение к большим контекстам через 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.

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

Для больших проектов AstraCode умеет строить локальный обзор модулей — суб-агент проходит по дереву, группирует файлы в модули (Cargo workspace → single crate → fallback по top-level директориям) и для каждого пишет короткое markdown-резюме (5–15 строк). Результат лежит как Obsidian-style vault в ~/.astracode/projects/<sha256>/:

text
~/.astracode/projects/3b38e074.../
├── index.md          # карта проекта
├── meta.json         # cwd, модель, дата, число модулей
└── modules/
    ├── astracode-cli.md
    ├── astracode-core.md
    └── ...

Команды:

text
/index build      # построить (или перестроить) индекс для текущей cwd
/index status     # показать состояние: модели, число модулей, дата
/index clear      # удалить vault текущего проекта

Подкоманда build уважает текущую TUI-cwd: если вы /cd /path/to/other-project, индекс построится для этой директории, а не той, откуда был запущен astracode. После завершения в чат выводится строка Индекс проекта построен: N/M модулей → ... — с путём к vault'у.

Прогресс идёт в нижнюю status-строку TUI («Индексирую проект…», «[1/8] формирую сводку astracode-cli…»). Это занимает обычно 1–5 минут в зависимости от размера проекта и скорости провайдера.

Когда полезно: при работе с незнакомым кодом — модель может смотреть в index.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