Мова

Інструкція — це звичайний текст. Кілька невеликих доповнень дають змогу точно сказати найважливіше, щоб люди могли це перевірити, а кожен агент розумів однаково. Цей огляд показує їх по одному, на тому самому прикладі: асистент, який планує чийсь день. Самі приклади наведено англійською, як вони написані.

Почніть зі звичайного тексту

Більша частина інструкції — це проза: для чого агент і як він має працювати. Короткий заголовок угорі дає документові назву та версію. Нотатки для людей, наприклад хто це написав і чому воно змінилося, стоять у самому кінці, і агент їх ніколи не отримує.

morning-assistant.md
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---

# Morning assistant

Prepare a useful daily brief.

MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.

---
authors: [Alex]
history:
  - summary: Preserve appointment status.
sources:
  - { title: Team guidance, uri: ./team.md }

Правила

Рядок, що починається з одного з п’яти слів, є правилом. Слово каже, наскільки правило суворе, а необов’язкова назва у квадратних дужках дає людям змогу на нього посилатися. BECAUSE: у наступному рядку наводить причину, і це допомагає агентові застосовувати правило розважливо.

СловоЩо воно означаєНаприклад
MUSTВимогаask Alex before changing an invitation.
SHOULDЗважене типове рішенняkeep the daily brief under 150 words.
MAYДозволений вибірsuggest a focus task when time is available.
NEVERЗаборонаreveal a private event to another person.
SHOULD NOTНебажана діяplan around it as a confirmed commitment.
Правило та його причина
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people.

Правило також може сказати, коли воно діє, у дужках після свого слова:

Правило з умовою
SHOULD NOT (if an invitation is tentative): plan around it as a confirmed commitment.
BECAUSE: the attendee has not accepted yet.

Політики та запобіжники

Правила, які належать разом, можна об’єднати в політику з власною назвою, щоб їх розглядали, поширювали й замінювали як одне ціле. Запобіжник позначає межу, яка має впадати в око кожному, хто читає.

Політика
:::policy{id=calendar title="Calendar policy"}
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people.

SHOULD[brief]: keep the daily brief under 150 words.

NEVER[privacy]: reveal a private event to another person.
:::
Запобіжник
:::guardrail{id=calendar-changes title="Calendar changes"}
Never send, delete, or move an invitation without the owner's approval.
:::

Змістовні інструкції

Коротких правил не завжди досить. Можна додати умови, приклад того, як виглядає добрий результат, і форму відповіді, якої ви очікуєте. Кожну частину позначено як те, чим вона є, тож агент відрізняє настанову від прикладу, а читач бачить їх чітко розкладеними.

Настанова, приклад і очікуваний результат
:::policy{id=planning title="Planning guidance"}
MUST[status] (if an invitation is tentative): preserve its tentative status.
BECAUSE: an unanswered invitation is not a commitment.

SHOULD[brief]: keep the daily brief under 150 words.
BECAUSE: the owner reads it on a phone.

NEVER[privacy]: reveal private event details to another person.
:::

:::example{title="Preserve the uncertainty"}
Your 09:00 catch-up is tentative. The 11:00 review is confirmed.
:::

:::output{response-format=markdown title="Daily brief"}
Use commitments, one focus task, and open decisions.
:::

Інструменти

Інструкція може назвати інструменти, якими агентові дозволено користуватися, наприклад календар, підключений через MCP, і сказати, які з його дій дозволені. Тут асистент може читати події та вільний час (events.list, availability.read), але ніколи не може видалити подію (events.delete).

Підключення інструмента
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

Навички

Навичка — це багаторазовий спосіб виконати одне завдання, записаний як кроки. Напишіть її один раз, дайте їй назву й посилайтеся на неї всюди, де вона потрібна. Ця називається «Prioritize the day» (визначити головне на день): вибрати одне корисне й посильне завдання, на якому варто зосередитися.

Навичка та посилання на неї
:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.

1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::

Use :skill[Prioritize the day]{ref=#prioritize}.

Люди

Інструкції часто залежать від людей: хто відповідає за рішення, хто має схвалити зміну. Оголосіть людину один раз, і правила зможуть посилатися на неї на ім’я. Кожен, хто читає, бачить, про кого йдеться, а інструменти можуть давати на неї посилання.

Людина та правило, яке її називає
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"}

MUST[approval]: ask :person[Alex]{ref=#owner} before changing an invitation.
BECAUSE: calendar changes affect other people.

Усе разом

Ось увесь асистент в одному файлі: заголовок, призначення, правило, календар, яким він може користуватися, навичка, невеликий робочий процес і нотатки для людей. Відкрийте редактор, щоб написати власну інструкцію; він показує той самий документ як сторінку, яку можуть читати люди.

morning-assistant.md
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---

# Morning assistant

Prepare a useful daily brief.

MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.


:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.

1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::

Use :skill[Prioritize the day]{ref=#prioritize}.

:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
  start:
    kind: manual
  read:
    kind: mcp.tool
    depends_on:
      - start
    server: calendar
    tool: events.list
    timeout: 30s
    retry:
      max: 2
      backoff: 2s
  draft:
    kind: agent
    depends_on:
      - read
    instruction: Prepare a daily brief. Keep tentative appointments tentative.
  review:
    kind: human
    depends_on:
      - draft
    question: Accept this daily brief?
    schema:
      type: string
      enum:
        - accept
        - revise
    timeout: 2h
  route:
    kind: switch
    depends_on:
      - review
    on: "{{ steps.review.output }}"
    cases:
      accept: accepted
      revise: revision
  accepted:
    kind: finish
    depends_on:
      - route
    output: "{{ steps.draft.output }}"
  revision:
    kind: finish
    depends_on:
      - route
    status: cancelled
    reason: The reviewer requested a revision.
:::

---
authors: [Alex]
history:
  - summary: Preserve appointment status.
sources:
  - { title: Team guidance, uri: ./team.md }

Куди далі