Issue tracker для агента: где живут spec и tickets

Зачем это нужно

Spec и tickets (см. 6.1) переживают сессию: их пишут в одном разговоре, а читают в других. Значит, им нужно место вне context window. Можно положить их файлами в репозиторий, но у этого варианта быстро появляются вопросы: кто отмечает ticket сделанным, где обсуждение, как коллега узнает, что вы задумали.

У команды разработки на такие вопросы давно есть ответ — issue tracker. Хорошая новость в том, что агент умеет читать и писать тот же tracker, что и вы. Spec становится issue, tickets — связанными issues, а следующая сессия получает задачу по номеру, а не по копипасте.

Как это устроено

Курс использует GitHub Issues: он бесплатный, и аккаунт у вас скорее всего уже есть. Идея переносится на Jira, Linear или любой другой tracker, к которому у агента есть доступ.

Мост между Claude Code и GitHub — консольный клиент gh. Документация Claude Code советует именно этот путь: CLI-инструменты — самый экономный по контексту способ работать с внешними сервисами, и Claude умеет через gh создавать issues, открывать pull requests и читать комментарии. Без gh агент может ходить в GitHub API напрямую, но неаутентифицированные запросы часто упираются в rate limit.

Второе, что нужно агенту, — знать, что tracker вообще существует и как им пользоваться. Для этого хватает двух файлов:

• указатель в AGENTS.md (или CLAUDE.md) — короткая секция: issues живут в GitHub, в таком-то репозитории, подробности в отдельном файле. Claude Code читает файл с инструкциями проекта в начале каждой сессии. Учтите: если рядом с AGENTS.md лежит CLAUDE.md, по умолчанию читается только CLAUDE.md, поэтому подключите в нём AGENTS.md строкой @AGENTS.md;
• отдельный файл с правилами, например docs/agents/issue-tracker.md: какими командами gh создавать, читать, комментировать и закрывать issues, какие labels ставить.

Указатель занимает пару строк в каждой сессии, а подробные правила агент читает только тогда, когда работает с tracker. Так стартовый контекст получает ссылку, а не весь справочник.

## Agent skills

### Issue tracker

Specs and tickets live as GitHub issues in <owner>/<repo>, managed with the `gh` CLI.
See `docs/agents/issue-tracker.md`.

В учебном проекте Cadence эти файлы пишет skill /setup-matt-pocock-skills: он осматривает репозиторий, предлагает tracker и после вашего согласия добавляет секцию в AGENTS.md и создаёт docs/agents/issue-tracker.md. Перед этим курс просит сделать собственную приватную копию репозитория командой npx ai-hero-cli fork: иначе ваши issues окажутся в общем репозитории курса вместе с чужими.

Практика

Проверьте, что gh видит ваш аккаунт:

gh auth status

В выводе должна быть строка Logged in to github.com account <ваш логин>. Если её нет, выполните gh auth login и пройдите вход через браузер.

Затем в репозитории, где уже есть указатель на tracker, откройте Claude Code, выполните /clear и попросите:

Add an issue to the issue tracker just as a test, just for a dummy.

Обратите внимание на порядок действий агента: сначала он читает docs/agents/issue-tracker.md, потом вызывает gh issue create и возвращает ссылку. Откройте её и закройте тестовый issue.

Подводные камни

• Чужой репозиторий. Агент создаёт issues там, куда смотрит gh и указатель. Если указатель ведёт на общий или рабочий репозиторий, тестовые issues увидят все.
• Правила только в голове. Без файла с правилами агент угадывает команды и labels каждый раз по-новому. Один файл делает поведение одинаковым от сессии к сессии.
• Весь справочник в AGENTS.md. Подробные правила tracker, положенные прямо в AGENTS.md, читаются в каждой сессии, даже когда tracker не нужен.

Вывод: spec и tickets живут в issue tracker, агент ходит туда через gh, а AGENTS.md хранит только короткий указатель на правила.

Проверь себя

Источники

• Anthropic, Best practices for Claude Code
• Anthropic, How Claude remembers your project
• По мотивам AI Coding Crash Course, AI Hero