Урок 5.3. Project Instructions

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

У каждого coding agent есть способ хранить инструкции проекта: CLAUDE.md, Cursor Rules, .roo/rules/, .cline/rules/, Kiro Steering и похожие механизмы. Эти файлы очень полезны: они позволяют не повторять базовые правила в каждом prompt.

Но есть ловушка. Когда project instructions начинают использовать как место для всего знания проекта, они превращаются в giant prompt:

• туда кладут requirements текущих features;
• историю решений;
• длинные архитектурные объяснения;
• временные TODO;
• examples на десятки страниц;
• правила, которые конфликтуют друг с другом.

В результате агент видит много текста, но хуже понимает, что действительно обязательно.

Главная цель урока - научиться писать короткие, стабильные и проверяемые project instructions, а подробности хранить в source documents и подключать progressive context.

Основная идея

Project instructions - это Level 1 context: короткие постоянные правила, которые агент должен соблюдать в большинстве задач.

Главный принцип:

Rules должны содержать короткие стабильные ограничения,
а не всю энциклопедию проекта.

Хорошие project instructions:

• короткие;
• стабильные;
• проверяемые;
• не содержат secrets;
• не дублируют feature specs;
• ссылаются на source documents вместо копирования всего текста;
• объясняют, когда агент должен остановиться.

Плохие project instructions пытаются заменить:

• specification;
• architecture docs;
• ADR;
• task plan;
• skill procedures;
• troubleshooting history;
• документацию фреймворка.

Ключевые термины

Где живут project instructions

Разные tools используют разные файлы и механизмы.

Примеры:

Названия отличаются, но инженерная задача одна: дать агенту стабильные правила проекта.

В курсе удобно держать vendor-neutral core:

PROJECT.md

и рядом тонкие adapters:

CLAUDE.md
.cursor/rules/...
.roo/rules/...
.cline/rules/...

Adapter не должен содержать новую логику. Он должен ссылаться на core или кратко повторять совместимые правила.

Vendor-neutral core и adapters

Такой подход снижает lock-in:

• базовые инженерные правила живут в одном месте;
• разные agents получают совместимые instructions;
• feature-specific context не попадает в always-on rules;
• skills остаются отдельными процедурами.

Agent replaceability

Agent replaceability - это способность проекта пережить смену coding agent без потери engineering process.

Команда может начать с Claude Code, потом часть задач делать в Codex, часть в Cursor, часть в Kiro. Если весь процесс живет только в tool-specific commands, chat history и локальных настройках одного инструмента, при смене агента команда теряет:

• правила работы;
• структуру specs;
• формат tasks;
• привычные gates;
• knowledge update loop;
• проверочные команды;
• критерии завершения.

Поэтому важно разделять durable process и adapter syntax.

Хороший тест:

Сможем ли мы отдать эту же task другому coding agent,
если он прочитает PROJECT.md, spec/design/tasks и нужные skills?

Если ответ "нет", значит слишком большая часть процесса спрятана в одном tool.

Практический minimum для agent replaceability:

• хранить product behavior в specs, а не в chat;
• хранить architecture decisions в ADR;
• хранить stable rules в vendor-neutral PROJECT.md;
• делать adapters короткими;
• не привязывать task format к одному agent;
• указывать verification commands явно;
• фиксировать completion evidence в commit/PR/agent run log.

Это не означает, что tool-specific features нельзя использовать. Можно и нужно использовать сильные стороны конкретного агента: plan mode, slash commands, hooks, MCP, custom skills, review agents. Но core process должен оставаться читаемым из репозитория.

Что должно быть в project rules

Примеры хороших rules:

## Scope and changes

- Do not modify files outside the allowed scope of the current task.
- If a required change is outside scope, stop and explain why.

## Verification

- Do not claim completion without running specified verification commands.
- Report commands, exit codes and result summary.

## Architecture

- Controllers call services; controllers must not import database client directly.
- Follow ADRs referenced by the current task.

## Dependencies

- Do not add new runtime dependencies without explicit approval.

## Safety

- Never write secrets to repository files.
- Ask for approval before destructive actions.

Это короткие правила, которые применяются почти всегда.

Что нельзя класть в project rules

Feature-specific requirements

Плохо:

Password reset token действует 15 минут.

Это должно жить в:

specs/password-reset/spec.md

Project rules могут сказать:

Read relevant feature spec before implementation.

Длинные процедуры

Плохо:

Как добавить endpoint:
1. ...
2. ...
30. ...

Это лучше вынести в skill:

skills/create-api-endpoint/SKILL.md

Project rules могут сказать:

Use relevant skill when available.

Историю обсуждений

Плохо:

В прошлом месяце мы спорили о token storage...

Итоговое решение должно быть в ADR.

Secrets

Никогда не кладите в rules:

• API keys;
• tokens;
• passwords;
• private URLs with credentials;
• production secrets;
• customer data.

Нестабильные TODO

Временные заметки должны жить в task files, issue tracker или plan, а не в always-on rules.

Хорошие и плохие project instructions

Rules должны быть такими, чтобы reviewer мог сказать: выполнено или нарушено.

Mode-specific instructions

Некоторые tools поддерживают режимы: Architect, Code, Debug, Ask, Review, Orchestrator, Plan/Act.

Mode-specific rules полезны, потому что разные режимы должны иметь разные permissions.

Пример:

Plan mode:
- Read files and produce plan.
- Do not edit production code.
- Identify open questions and risks.

Code mode:
- Edit only allowed scope.
- Follow current task.
- Run verification.

Review mode:
- Review diff against spec, architecture constraints and tests.
- Do not rewrite implementation unless explicitly asked.

Если tool не поддерживает режимы явно, их можно имитировать task prompt'ами и permissions.

Минимальный PROJECT.md

Пример:

# Project Instructions

## Source of truth

- Product behavior lives in `specs/**/spec.md`.
- Architecture decisions live in `docs/architecture/adr/`.
- Task scope lives in `specs/**/tasks.md`.

## Scope

- Modify only files allowed by the current task.
- Stop if implementation requires changes outside allowed scope.

## Architecture

- Controllers call services.
- Services contain application logic.
- Repositories own persistence access.
- Do not import database client from controllers.

## Verification

- Run specified verification commands before completion.
- Report commands, exit codes and result summary.

## Safety

- Do not add dependencies without approval.
- Do not write secrets to repository.
- Ask before destructive or irreversible actions.

## Completion

Return:
- summary;
- changed files;
- verification evidence;
- acceptance criteria status;
- unresolved issues.

Это не полный стандарт для всех проектов, но хорошая стартовая форма.

Adapter examples

CLAUDE.md

# Claude Code Project Instructions

Follow `PROJECT.md`.

For every coding task:
- read the current task file;
- read referenced spec/design/ADR sections;
- respect allowed scope;
- run verification;
- report evidence.

Cursor Rules

Use `PROJECT.md` as the source for stable project rules.
Do not duplicate feature-specific requirements here.

When implementing a task, prefer the local patterns in the target module.

Roo/Cline style

# Code mode rules

- Use current Agent Task as scope boundary.
- Do not perform architecture redesign in Code mode.
- Stop when product behavior is ambiguous.

Adapters должны быть тонкими. Если нужно менять правило, лучше менять core и обновлять adapters только при необходимости.

Как поддерживать rules

Project instructions должны эволюционировать, но медленно.

После task спросите:

Появилось ли новое стабильное правило?
    ↓ YES
Project rules

Появилась повторяемая процедура?
    ↓ YES
Skill

Появилось architecture decision?
    ↓ YES
ADR

Изменилось product behavior?
    ↓ YES
Spec

Не каждое наблюдение становится rule. Если добавить все, rules станут шумом.

Практика: написать короткий rules-файл

Создайте:

PROJECT.md

или, если не хотите пока добавлять root-level файл:

labs/05-context/PROJECT.md

Заполните разделы:

# Project Instructions

## Source of truth

## Scope

## Architecture

## Verification

## Safety

## Completion format

Ограничения:

• не больше 25 rules всего;
• не включать feature-specific requirements;
• не включать secrets;
• минимум 5 rules должны быть проверяемыми;
• минимум 3 rules должны говорить, когда agent должен остановиться;
• добавить ссылки на specs/, docs/architecture/adr/, tasks.md.

Затем создайте один adapter:

labs/05-context/CLAUDE.md

или аналог для вашего coding agent.

Типичные ошибки

Ошибка 1. Делать rules слишком длинными

Если project instructions длиннее большинства specs, они начинают вредить context quality.

Ошибка 2. Дублировать feature specs

Product behavior должен жить в spec.md. Rules должны говорить, что spec нужно читать.

Ошибка 3. Класть procedures в rules

Повторяемые процедуры должны стать skills. Это тема следующего модуля.

Ошибка 4. Не проверять rules на исполнимость

Если rule нельзя проверить, agent и reviewer будут трактовать ее по-разному.

Ошибка 5. Делать adapters независимыми копиями

Если CLAUDE.md, Cursor Rules и .roo/rules/ расходятся, разные agents будут соблюдать разные правила.

Критерии готовности

После урока студент должен уметь:

• объяснить назначение project instructions;
• отличить stable rule от feature-specific requirement;
• написать короткий vendor-neutral PROJECT.md;
• создать tool-specific adapter;
• объяснить, что нельзя класть в rules;
• понять, когда knowledge должно стать spec, ADR, skill или rule.

Краткое резюме

Project instructions - это Level 1 context для coding agent. Они должны задавать стабильные правила поведения: scope, architecture, verification, safety и completion format.

Они не должны заменять specification, ADR, tasks или skills. Чем короче и проверяемее rules, тем лучше они работают в agent workflow.

Оптимальная структура:

PROJECT.md
    ↓
thin adapters for specific agents
    ↓
task-specific context
    ↓
skills when procedure is needed

Вопросы для самопроверки

1. Почему project rules не должны содержать feature-specific requirements?
2. Что лучше положить в skill, а не в project instructions?
3. Чем vendor-neutral core полезнее нескольких независимых adapters?
4. Какие rules должны заставлять агента остановиться?
5. Как понять, что новое знание должно стать ADR, spec, skill или rule?

Что дальше

Модуль V завершает тему контекста: мы научились собирать context package, раскрывать context progressive layers и писать короткие project instructions.

В следующем модуле мы перейдем к Skills. Skills позволяют вынести повторяемые процедуры из always-on rules и подключать их только тогда, когда агенту действительно нужен конкретный workflow.