Чётко и прямо

Главная мысль раздела простая: модель работает тем лучше, чем меньше ей приходится догадываться. Anthropic в оригинале формулирует это так: «Claude responds well to clear, explicit instructions. Being specific about your desired output can help enhance results». То есть пишите явно: какой результат хотите, в каком формате, с какими ограничениями. Не рассчитывайте, что модель сама догадается, что вы под «нормально» имели в виду.

Anthropic советует представлять Claude как нового, очень способного сотрудника, который только-только пришёл в команду. Он умный, но про ваш проект ничего не знает: ни как у вас устроены заказы, ни как считается стоимость лестницы, ни почему `markupMaterialsPct` лежит в одной таблице, а наценка на работы — в другой. Чем точнее вы объясните контекст и задачу, тем точнее ответ.

Золотое правило (формулировка Anthropic): «Show your prompt to a colleague with minimal context on the task and ask them to follow it. If they’d be confused, Claude will be too». Покажите свой промпт коллеге, у которого нет контекста. Если он запутался — Claude тоже запутается.

Из этого вытекают две практические рекомендации:

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

Create an analytics dashboard

Create an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation.

Сделай страницу списка заказов на React

Сделай страницу списка заказов на React. Бэкенд — Ktor + JDBI,
эндпоинт уже есть: GET /api/orders возвращает список из OrderService.
Нужно: таблица с колонками номер, заказчик, статус, сумма, срок;
фильтр по статусу и поиск по номеру; пагинация по 50 записей;
ссылка на карточку заказа. Стили — как у соседних страниц проекта.
Если у тебя есть вопросы по полям ответа — сначала загляни в
OrderService и OrderRepository, не выдумывай схему.

Добавляйте контекст — это улучшает результат

Anthropic пишет: «Providing context or motivation behind your instructions, such as explaining to Claude why such behavior is important, can help Claude better understand your goals and deliver more targeted responses». То есть объясняйте не только «что делать», но и «зачем». Модель достаточно сообразительна, чтобы обобщить объяснение и применить его в смежных случаях.

NEVER use ellipses

Your response will be read aloud by a text-to-speech engine, so never use ellipses since the text-to-speech engine will not know how to pronounce them.

Не используй var в Kotlin

В этом проекте мы держим модели заказов и материалов иммутабельными:
все DTO — data class с val, в OrderService и MaterialService нет
изменяемого состояния, это упрощает тесты в IntegrationTestBase.
Поэтому: не используй var, не вводи mutableListOf там, где можно
listOf или toList(). Если без var обойтись нельзя — поясни в
комментарии, почему.

Используйте примеры

Этот подраздел в оригинале короткий и подробно раскрыт в отдельной статье «Примеры в промпте». Здесь Anthropic фиксирует главное: «Examples are one of the most reliable ways to steer Claude's output format, tone, and structure. A few well-crafted examples (known as few-shot or multishot prompting) can dramatically improve accuracy and consistency».

Когда добавляете примеры, делайте их:

• Релевантными: близкими к вашему реальному случаю. Если просите Claude писать тесты в стиле проекта — пример из OrderRepositoryIT работает лучше, чем абстрактный «Hello world test».
• Разнообразными: покрывайте крайние случаи и не делайте все примеры однотипными — иначе модель подхватит случайную закономерность, которую вы не имели в виду.
• Структурированными: заворачивайте примеры в теги <example> (несколько примеров — внутри <examples>), чтобы модель отличала их от инструкций.

Структурируйте промпты XML-тегами

Когда промпт смешивает инструкции, контекст, примеры и переменные входные данные, модель легче парсит его, если каждый кусок обёрнут в свой тег. Anthropic называет это так: «XML tags help Claude parse complex prompts unambiguously». Для Claude Code это особенно полезно, когда вы скармливаете ему длинный кусок чужого кода рядом с вашей задачей.

Хорошие практики:

• Используйте одни и те же названия тегов от промпта к промпту — пусть у вас будет свой словарь: <instructions>, <context>, <input>, <file>.
• Вкладывайте теги, если у контента есть естественная иерархия: несколько документов внутри <documents>, каждый внутри <document index="n">.

Дайте Claude роль

Anthropic: «Setting a role in the system prompt focuses Claude's behavior and tone for your use case. Even a single sentence makes a difference». Системный промпт — это инструкция верхнего уровня, которая задаёт Claude роль на всю беседу.

В оригинале здесь идёт пример вызова API из Python — для вас он нерелевантен, потому что вы не вызываете модель из кода, а работаете через Claude Code Desktop. Эквивалент роли в Claude Code — это файл CLAUDE.md в корне проекта: всё, что вы туда напишете, модель читает в каждом разговоре. Например:

Ты помогаешь мне с веб-системой для производства лестниц.
Стек: Kotlin + Ktor + JDBI + PostgreSQL на бэкенде, React на фронте.
Я не профессиональный программист — объясняй неочевидные решения
коротко и по делу. Пиши идиоматичный Kotlin: data class, val,
никаких var без причины. Тесты — поверх IntegrationTestBase, как
в OrderRepositoryIT и JwtFilterTest. Не выдумывай имена методов,
которых нет в OrderService/MaterialService — сначала проверь.

Длинный контекст

Когда вы скармливаете модели большие документы или входные данные (от 20 тысяч токенов и больше), структура промпта начинает заметно влиять на качество. Это редкий сценарий для повседневной работы в Claude Code, но полезно знать правила.

• Длинные данные — в начало промпта. Anthropic: «Place your long documents and inputs near the top of your prompt, above your query, instructions, and examples. This can significantly improve performance across all models».
• Структурируйте документы XML-тегами. Когда документов несколько, заворачивайте каждый в <document> с подтегами <document_content> и <source> (плюс другие метаданные).
  Пример мультидокументной структуры

  <documents>
    <document index="1">
      <source>annual_report_2023.pdf</source>
      <document_content>
        {{ANNUAL_REPORT}}
      </document_content>
    </document>
    <document index="2">
      <source>competitor_analysis_q2.xlsx</source>
      <document_content>
        {{COMPETITOR_ANALYSIS}}
      </document_content>
    </document>
  </documents>
  
  Analyze the annual report and competitor analysis. Identify strategic advantages and recommend Q3 focus areas.
  

• Просите модель сначала процитировать релевантное. Для длинных документов попросите Claude сначала выписать релевантные цитаты, и только потом сделать задачу. Это помогает модели «прорезаться» через шум остального текста.
  Пример с извлечением цитат

  You are an AI physician's assistant. Your task is to help doctors diagnose possible patient illnesses.
  
  <documents>
    <document index="1">
      <source>patient_symptoms.txt</source>
      <document_content>
        {{PATIENT_SYMPTOMS}}
      </document_content>
    </document>
    <document index="2">
      <source>patient_records.txt</source>
      <document_content>
        {{PATIENT_RECORDS}}
      </document_content>
    </document>
    <document index="3">
      <source>patient01_appt_history.txt</source>
      <document_content>
        {{PATIENT01_APPOINTMENT_HISTORY}}
      </document_content>
    </document>
  </documents>
  
  Find quotes from the patient records and appointment history that are relevant to diagnosing the patient's reported symptoms. Place these in <quotes> tags. Then, based on these quotes, list all information that would help the doctor diagnose the patient's symptoms. Place your diagnostic information in <info> tags.
  

В терминах вашего проекта это могло бы выглядеть так: если просите Claude разобраться, как считается стоимость заказа, и кидаете ему содержимое OrderCalculationService.kt, MaterialService.kt и пары репозиториев — заверните каждый файл в свой <file index="n"> с <path> и попросите сначала выписать строки, где встречается markupMaterialsPct, и только потом объяснить логику.

Самоидентификация модели

Этот подраздел Anthropic держит для тех, кто встраивает модель в своё приложение и хочет, чтобы Claude правильно представлялся пользователю. Для вас это сейчас неактуально — вы не строите приложение поверх API. Если когда-нибудь будет актуально, шаблон промпта из оригинала такой:

The assistant is Claude, created by Anthropic. The current model is Claude Opus 4.7.

А для приложений, которым нужно знать точную строку модели:

When an LLM is needed, please default to Claude Opus 4.7 unless the user requests otherwise. The exact model string for Claude Opus 4.7 is claude-opus-4-7.