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 Claude Code 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 .claude/CLAUDE.md for tracked-context-managed projects so Claude Code has first-class project memory.
• Keep .claude/CLAUDE.md optimized for Claude Code, not as a thin @AGENTS.md import. Reference Claude-specific locations when relevant: .claude/settings.json, .claude/skills/, .claude-plugin/, /memory, /context, /hooks, /mcp, /permissions, /doctor, /status.
• Do not create root CLAUDE.md by default; .claude/CLAUDE.md is the rldyour 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 durable AI context. They should be:

• Restored locally from main branch via python3 "$(git rev-parse --show-toplevel)"/plugins/rldyour-flow/scripts/flow_post_task_state.py --tracked-context review (canonical cross-plugin path per PATTERNS-01-CANONICAL; works without declaring rldyour-flow in rldyour-rules plugin.json because both plugins co-exist inside the same marketplace relative-source layout under ./plugins/<name>).
• Ignored through .git/info/exclude (tracked-context block installed automatically).
• Published to main branch via flow-post-task-sync.
• Never committed to normal product branches (main, feature branches).

Repositories that are themselves agent tooling (like rldyour-claudecode itself) may intentionally track selected instruction templates as product files - for example a system/CLAUDE.md template that gets installed into user projects.

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

Anti-patterns

• Reduce .claude/CLAUDE.md к thin @AGENTS.md import (нарушает rldyour rule).
• Create root CLAUDE.md для new projects (.claude/CLAUDE.md - preferred path).
• Commit AGENTS.md/CLAUDE.md/REVIEW.md в нормальные продуктовые ветки (use tracked-context).
• Store secrets / tokens / chat history в instruction docs.
• Skip ADR для irreversible decisions (architecture, framework, DB choice).
• Update instruction docs для mechanical formatting changes (только durable facts).