Когда это нужноWhen to reach for itКоли це потрібно
Перед написанием спеки: нужно понять, как что-то устроено сейчас, какие файлы и имена задействованы в области, какие есть ограничения и где риски и пробелы.Before writing a spec: you need to know how something currently works, which files and names are involved in an area, what constraints apply, and where the risks and gaps are.Перед написанням спеки: треба зрозуміти, як щось влаштовано зараз, які файли та імена задіяні в галузі, які є обмеження та де ризики й прогалини.
ТребованияRequirementsВимоги
- Где доступноAvailable inДе доступно
- Каждая загрузка kitEvery download of the kitКожне завантаження kit
- К чему обращаетсяWhat it touchesДо чого звертається
- Читает файлы проектаReads the files of your projectЧитає файли проєкту
- Работает сWorks withПрацює з
- Сделано для Claude Code; другие агенты адаптируютBuilt for Claude Code; other agents adapt itЗроблено для Claude Code; інші агенти адаптують
- Где выполняются шагиWhere the steps happenДе виконуються кроки
- Чат вашего агента и ваши собственные файлы. Ни то ни другое не интерфейс этого сайта, поэтому шаги описаны текстом, а не скриншотами.Your agent's chat and your own files. Neither is an interface of this site, so the steps are text and not screenshots.Чат вашого агента і ваші власні файли. Ні те, ні інше не є інтерфейсом цього сайту, тому кроки описано текстом, а не скриншотами.
- Где это лежит в kitWhere it lives in the kitДе це лежить у kit
.claude/agents/solution-researcher.md
Прежде чем начатьBefore you startПерш ніж почати
Режим «только чтение» держится на наборе инструментов, а не только на промпте: агент поставляется с tools: Read, Grep, Glob и без Bash. Если ваш индекс кода - это CLI, выдайте только Bash(<index> query *) на чтение и ничего, что умеет писать, переносить или удалять.Read-only is enforced by the tool set, not only by the prompt: the agent ships with tools: Read, Grep, Glob and without Bash. If your code index is a CLI, grant a read-only Bash(<index> query *) and nothing that can write, move or delete.Режим «лише читання» тримається на наборі інструментів, а не лише на промпті: агент постачається з tools: Read, Grep, Glob і без Bash. Якщо ваш індекс коду - це CLI, видайте лише Bash(<index> query *) на читання й нічого, що вміє писати, переносити чи видаляти.
ШагиStepsКроки
- Назовите тему или область для изучения. Сначала убедитесь, что заполнители в файле агента (название проекта, язык чата, язык артефактов, зоны только для чтения) заполнены под ваш проект. В чате он говорит на языке, заданном для чата; отчёт и все ссылки на код - на языке, заданном для артефактов.Name the topic or area to investigate. First make sure the placeholders in its file (project name, chat language, artifact language, read-only zones) are filled in for your project. It chats in the language you set for chat; the report and every code reference are in the language you set for artifacts.Назвіть тему чи галузь для вивчення. Спершу переконайтеся, що заповнювачі у файлі агента (назва проєкту, мова чату, мова артефактів, зони лише для читання) заповнені під ваш проєкт. У чаті він говорить мовою, заданою для чату; звіт і всі посилання на код - мовою, заданою для артефактів.
- Он привязывает тему: определяет затронутый модуль или область и вероятные поверхности, опираясь на карту репозитория или документ об архитектуре.It anchors the topic: it identifies the affected module or area and the likely surfaces, using the repo map or the architecture doc.Він прив'язує тему: визначає зачеплений модуль чи галузь і ймовірні поверхні, спираючись на карту репозиторію або документ про архітектуру.
- Он быстро выбирает маршрут: читает по порядку и останавливается, как только источник ответил. Сначала карта репозитория, затем символы, найденные через grep или ваш индекс кода (до чтения целых деревьев), затем нужный документ об архитектуре, эксплуатации или стеке, затем непосредственно относящиеся файлы реализации.It routes fast, reading in order and stopping as soon as a source answers: the repo map, then symbols located with grep or your code index before whole trees are read, then the relevant architecture, ops or stack doc, then the directly relevant implementation files.Він швидко добирає маршрут: читає по порядку й зупиняється, щойно джерело відповіло. Спершу карта репозиторію, потім символи, знайдені через grep або ваш індекс коду (до читання цілих дерев), потім потрібний документ про архітектуру, експлуатацію чи стек, потім безпосередньо відповідні файли реалізації.
- Пробелы, оставленные документами, он закрывает точечным поиском: все места вызова ключевого символа, существующие флаги функций для области, существующие приёмы обработки ошибок в похожих операциях, комментарии TODO и FIXME в области и тесты, которые её уже покрывают.It fills the gaps the docs left with targeted searches: all call sites of the key symbol, existing feature flags for the area, existing error-handling patterns for similar operations, TODO and FIXME comments in the area, and the tests that already cover it.Прогалини, залишені документами, він закриває точковим пошуком: усі місця виклику ключового символу, наявні прапорці функцій для галузі, наявні прийоми обробки помилок у схожих операціях, коментарі TODO і FIXME в галузі та тести, що її вже покривають.
- Он фиксирует ограничения от любого API платформы или среды выполнения и поведения, зависящего от версии, которых касается функциональность, и нужен ли слой совместимости. И отмечает риски: файлы возле лимита размера, которые придётся менять, изменяемый код без тестов, циклические зависимости, риски параллелизма, ввод-вывод не в том потоке, дыры в таймаутах и повторах при работе с сетью.It notes constraints from any platform or runtime API or version-gated behaviour the feature touches, and whether a compat shim is needed. It flags risks: files near the size budget that will be touched, changed code with no tests, circular dependencies, concurrency hazards, I/O on the wrong thread, and timeout or retry gaps on the network.Він фіксує обмеження від будь-якого API платформи чи середовища виконання та поведінки, залежної від версії, яких торкається функціональність, і чи потрібен шар сумісності. І позначає ризики: файли біля ліміту розміру, які доведеться змінювати, змінюваний код без тестів, циклічні залежності, ризики паралелізму, введення-виведення не в тому потоці, дірки в таймаутах і повторах під час роботи з мережею.
- Он возвращает один Markdown-отчёт: «Research report:» и тема, девять разделов (их названия остаются английскими): Affected scope; Current architecture - key files; Reusable patterns found in the codebase; Data flow (current); Constraints; Feature flags / config relevant to this area; Risks; Test coverage summary; Open questions for the spec author. Раздел опускается, только если он действительно неприменим, и с указанием причины.It returns one Markdown report, "Research report:" plus the topic, in nine sections: Affected scope; Current architecture - key files; Reusable patterns found in the codebase; Data flow (current); Constraints; Feature flags / config relevant to this area; Risks; Test coverage summary; Open questions for the spec author. A section is omitted only if it is genuinely not applicable, with the reason.Він повертає один Markdown-звіт: «Research report:» і тема, дев'ять розділів (їхні назви лишаються англійськими): Affected scope; Current architecture - key files; Reusable patterns found in the codebase; Data flow (current); Constraints; Feature flags / config relevant to this area; Risks; Test coverage summary; Open questions for the spec author. Розділ пропускається, лише якщо він справді не застосовний, і з указанням причини.
- Вы несёте отчёт тому, кто пишет спеку. Его последний раздел перечисляет пронумерованные вопросы, требующие продуктового или архитектурного решения: из одного кода на них не ответить. Шагов реализации агент не предлагает.You take the report to whoever writes the spec. Its last section lists numbered questions that need a product or architecture decision, because code alone cannot answer them. The agent proposes no implementation steps.Ви несете звіт тому, хто пише спеку. Його останній розділ перелічує пронумеровані питання, що потребують продуктового чи архітектурного рішення: з самого коду на них не відповісти. Кроків реалізації агент не пропонує.
Что вы должны увидетьWhat you should seeЩо ви маєте побачити
Один Markdown-отчёт, где каждое утверждение опирается на реальный путь к файлу и, при необходимости, диапазон строк, а в вашем проекте ничего не изменилось. Вопросы, на которые из одного кода не ответить, пронумерованы в конце для автора спеки.One Markdown report in which every claim cites a real file path and, where useful, a line range, and in which nothing in your project has changed. Questions that code alone cannot answer are numbered at the end for the spec author.Один Markdown-звіт, де кожне твердження спирається на реальний шлях до файлу та, за потреби, діапазон рядків, а у вашому проєкті нічого не змінилося. Питання, на які з самого коду не відповісти, пронумеровано в кінці для автора спеки.
СоветыTipsПоради
- Отчёт создан, чтобы питать стратегическую спеку: передайте его шагу со спекой как доказательную базу. Сам агент плана не пишет: шагов реализации он не предлагает.The report is built to feed a strategic spec: hand it to the spec step as the evidence. The agent itself writes no plan, because it never proposes implementation steps.Звіт створений, щоб живити стратегічну спеку: передайте його кроку зі спекою як доказову базу. Сам агент плану не пише: кроків реалізації він не пропонує.
- Прежде чем полагаться на отчёт, проверьте выборку: откройте два-три указанных пути. Правило самого агента - не писать находку, которую нельзя подкрепить реальным путём, так что утверждение без пути является дефектом отчёта.Check a sample before you rely on it: open two or three of the cited paths. The agent's own rule is not to write a finding it cannot cite to a real path, so a claim without a path is a defect in the report.Перш ніж покладатися на звіт, перевірте вибірку: відкрийте два-три вказані шляхи. Правило самого агента - не писати знахідку, яку не можна підкріпити реальним шляхом, тож твердження без шляху є дефектом звіту.
- В проекте без кода вопросы остаются, а заголовки меняются: «current architecture» превращается в текущую структуру и в то, кто чем владеет, а «test coverage» - в то, за какими частями стоит проверка, а за какими нет.On a project that is not code, the questions stay and the headings change: "current architecture" becomes the current structure and who owns each part, "test coverage" becomes which parts have a check behind them and which do not.У проєкті без коду питання лишаються, а заголовки змінюються: «current architecture» перетворюється на поточну структуру й на те, хто чим володіє, а «test coverage» - на те, за якими частинами стоїть перевірка, а за якими ні.
- Ваши зоны только для чтения этому агенту открыты: «только для чтения» значит «никогда не меняется», а в них часто лежит именно тот сырой материал, на который должна ссылаться находка. Он их читает и всё равно ничего не правит.Your read-only zones are open to this agent: read-only means never modified, and they often hold exactly the raw material a finding must cite. It reads them and still edits nothing.Ваші зони лише для читання цьому агентові відкриті: «лише для читання» означає «ніколи не змінюється», а в них часто лежить саме той сирий матеріал, на який має посилатися знахідка. Він їх читає і все одно нічого не правит.
- Если исследование - часть большей работы, где потом будут сборка и ревью, начните с rd-lead. Для прохода «сначала исследуй», запускаемого из вашего чата, см. research.If the investigation is part of a larger job that will also build and review, start with rd-lead. For a research-first pass run from your own chat, see research.Якщо дослідження - частина більшої роботи, де потім будуть збірка й рев'ю, почніть із rd-lead. Для проходу «спершу досліди», що запускається з вашого чату, див. research.
Связанные функцииRelated functionsПов'язані функції
- Поручить нетривиальную работу ведущему агентуHand a non-trivial job to a lead agentДоручити нетривіальну роботу ведучому агентовіОдин ведущий агент ведёт запрос от первого чтения до проверенной работы: оценивает задачу, выбирает самый лёгкий подходящий путь и передаёт части другим агентам.One lead agent takes a request from first read to verified work: it classifies the job, picks the lightest path that fits and hands parts to other agents.Один ведучий агент веде запит від першого читання до перевіреної роботи: оцінює завдання, обирає найлегший придатний шлях і передає частини іншим агентам.
- Изучить область, прежде чем её менятьInvestigate an area before you change itВивчити ділянку, перш ніж її змінюватиОдин продуманный проход чтения оставляет черновое досье и, для тикета, долговечные выводы, чтобы никто не искал одно и то же пять раз.One deliberate reading pass leaves a scratch dossier and, for a ticket, durable findings, so nobody greps the same things five times.Один продуманий прохід читання лишає чорнове досьє і, для тікета, довговічні висновки, щоб ніхто не шукав те саме п'ять разів.
- Превратить описание фичи в утверждённую стратегическую спекуTurn a feature description into an approved strategic specПеретворити опис фічі на затверджену стратегічну спеку
/specпишет, что и зачем нужно в фиче, без имён классов и путей к файлам, утверждает и передаёт/spec-tech. Мелкую задачу делает на месте./specwrites the what and why of a feature with no class names or file paths, approves it and passes it to/spec-tech. A small task is built in place./specпише, що й навіщо потрібно у фічі, без назв класів і шляхів до файлів, затверджує та передає/spec-tech. Дрібну задачу робить на місці. - Научить агента искать, а не угадыватьMake the agent look things up instead of guessingНавчити агента шукати, а не вгадуватиФиксированный порядок поиска и, для большого проекта, поддерживаемый индекс вашего материала: каждый путь, символ и API, названные агентом, проверены.A fixed order for finding things and, for a big project, a maintained index of your material, so every path, symbol and API the agent states has been verified.Фіксований порядок пошуку і, для великого проєкту, підтримуваний індекс вашого матеріалу: кожен шлях, символ і API, названі агентом, перевірені.