project-instructions-policy

name	project-instructions-policy
description	Политика project-инструкций: AGENTS.md, .claude/CLAUDE.md, REVIEW.md, ADRs (MADR 4.0.0). Используй для: правила проекта, инструкции, документация, ADR, долгоживущая документация. EN triggers: project rules, project instructions, ADR, MADR, write durable docs, update AGENTS.md, update CLAUDE.md, instruction policy.

Project Instructions Policy

Purpose

Keep durable project instructions useful for future sessions without turning them into chat history or generic advice.

Rules

• Create or update AGENTS.md when durable root-level project rules, setup commands, quality gates, architecture constraints, deploy contracts, or workflow guidance change. AGENTS.md is the cross-tool standard root project-instruction file (see https://agents.md/).
• Keep AGENTS.md concise; it is loaded as a high-signal entry point and instruction size matters.
• Create or update project-specific instruction files for managed projects so the agent has first-class project memory.
• Keep instruction files optimized for the active agent, not as minimal re-exports. Reference agent-specific locations when relevant: configuration files, skill directories, command directories, memory directories, permission configs, health check tools, and status commands.
• Do not create root CLAUDE.md by default; .claude/CLAUDE.md is the project memory path.
• Create or update REVIEW.md when review-specific rules are durable and materially help future review agents.
• Create ADRs (MADR 4.0.0 format) for important architecture, technology, dependency, deployment, security, or irreversible design decisions.
• Repository docs, instructions, ADRs, memories, plans, comments, and commits are English. User-facing conversation with the user is Russian.
• Do not store secrets, personal tokens, local-only credentials, private cookies, or chat transcripts in docs.

Agent-Only Files And tracked context

In normal product repositories, instruction files (AGENTS.md, .claude/CLAUDE.md, REVIEW.md) are agent-only context. They should be:

• Restored locally from tracked context branch via the project sync script.
• Ignored through .git/info/exclude (tracked context block installed automatically).
• Published to tracked context branch via sync workflow.
• Never committed to normal product branches (main, feature branches).

Repositories that are themselves agent tooling may intentionally track selected instruction templates as product files.

Read references/project-instructions-and-adrs.md before creating or updating durable instruction files.

Anti-patterns

• Reduce .claude/CLAUDE.md to a thin @AGENTS.md import (violates project rule).
• Create root CLAUDE.md for new projects (.claude/CLAUDE.md is the preferred path).
• Commit AGENTS.md/CLAUDE.md/REVIEW.md into normal product branches (use tracked context).
• Store secrets / tokens / chat history in instruction docs.
• Skip ADR for irreversible decisions (architecture, framework, DB choice).
• Update instruction docs for mechanical formatting changes (only durable facts).