docs(agents): scope agent guidance

[Audionut]

General guidance

This PR keeps the always-loaded agent guidance small, stable, and action-oriented while preserving deeper project guidance in scoped files that agents can load when relevant. The intent is not to remove pre-existing guidance; it is to make it more usable by Codex and Claude by separating baseline repo rules from frontend, lint-policy, and architecture references.

This follows the official token/context and memory guidance reviewed for this change:

• OpenAI's token docs explain that input text is tokenized and counted as request input, and that large prompts should be shortened, chunked, summarized, or pre-processed when needed: https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them
• OpenAI's prompt caching docs say cache hits require exact prefix matches and recommend placing static instructions/examples at the beginning while moving variable content later: https://platform.openai.com/docs/guides/prompt-caching
• Anthropic's Claude Code memory docs say Claude loads CLAUDE.md, supports importing AGENTS.md, loads directory-walked CLAUDE.md files into context, and follows concise/specific instructions more consistently: https://docs.anthropic.com/en/docs/claude-code/memory
• Anthropic's prompt caching docs similarly recommend keeping static instructions/context at the beginning and caching reusable prompt prefixes: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching

What changed

• AGENTS.md

  • Condensed the root agent instructions from a broad all-in-one document into always-loaded repo rules: collaboration expectations, repo map, required commands, backend conventions, code shape, path/security rules, API/database rules, and PR/reporting expectations.
  • Added explicit conditional routing to docs/architecture.md before cross-module data-flow/service-boundary/API-routing work.
  • Added explicit conditional routing to docs/linting.md only when lint output requires policy judgment; otherwise the actual lint config/tool output remains source of truth.
  • Added explicit routing to web/AGENTS.md before frontend/i18n/React work.
  • Reason: OpenAI token docs count instructions as input tokens, and Anthropic memory docs emphasize concise/specific instructions. Keeping root memory shorter reduces default prompt load while retaining guidance through scoped references.

• web/AGENTS.md

  • Moved frontend, React Effects, i18n, language-addition, translation, and TorrentDetails live-state notes into a frontend-scoped agent file.
  • Reason: Anthropic documents directory-walked CLAUDE.md loading and imports, so frontend-specific guidance is better loaded when agents operate under web/ instead of always consuming root context. This also matches OpenAI token guidance by limiting default input to relevant instructions.

• web/CLAUDE.md

  • Added @AGENTS.md so Claude Code can load the frontend-scoped rules from web/AGENTS.md when working in web/.
  • Reason: Anthropic's Claude Code memory docs state that Claude reads CLAUDE.md, not AGENTS.md, and recommend importing AGENTS.md with @AGENTS.md when both tools should share instructions.

• docs/architecture.md

  • Moved the architecture quick reference and core data-flow notes into an internal reference document.
  • Reason: architecture notes are important for cross-module changes, but not every agent task needs them in the root prompt. The root file now points to this document exactly when that context matters.

• docs/linting.md

  • Moved the linter threshold table and lint-policy notes into an internal reference document.
  • Reason: lint thresholds can drift from config/tool output, so the root file now keeps the durable behavior rule and directs agents to the detail document only for ambiguous lint judgment. This preserves the guidance without making it the main always-loaded source of truth.

• .gitignore

  • Unignored docs/architecture.md and docs/linting.md so these internal reference docs can be tracked despite the existing docs/* ignore.

• CONTRIBUTING.md

  • Updated the agent-guidance pointer to reference AGENTS.md and web/AGENTS.md.

Validation

• Reviewed the changes against the official OpenAI token/counting and prompt-caching docs plus Anthropic Claude Code memory and prompt-caching docs listed above.
• Verified the staged diff is documentation/guidance only.
• No build/test run: no runtime code, generated assets, OpenAPI, database schema, or frontend source changed.

Summary by CodeRabbit

• Documentation
  • Updated and reorganized internal development guidelines, including architecture reference, linting standards, and contributor conventions for clearer project guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: f187260d-b768-4a37-915b-a87ad53192a3

📥 Commits

Reviewing files that changed from the base of the PR and between 8b278e5 and 9c07fd5.

📒 Files selected for processing (7)

• .gitignore
• AGENTS.md
• CONTRIBUTING.md
• docs/architecture.md
• docs/linting.md
• web/AGENTS.md
• web/CLAUDE.md

---

Walkthrough

Documentation is restructured to consolidate agent guidelines and introduce architecture/linting references. The root AGENTS.md is condensed and references new web/AGENTS.md for frontend rules. New docs/architecture.md and docs/linting.md provide development references, and contributing documentation is updated to direct readers to these files.

Changes

Agent Guidelines Consolidation and Reference Documentation

Layer / File(s)	Summary
Agent guidelines restructuring and frontend separation AGENTS.md, web/AGENTS.md, web/CLAUDE.md	AGENTS.md is condensed to remove frontend/i18n details; new web/AGENTS.md introduces React/Vite/TypeScript/Tailwind conventions, testing (Vitest + React Testing Library), useEffect patterns, i18n namespace/locale workflows, and streaming vs polling guidance for TorrentDetailsPanel. web/CLAUDE.md header references shared AGENTS.md.
Architecture and linting reference documentation docs/architecture.md, docs/linting.md	docs/architecture.md documents module map, data flow through SyncManager/pooling/cached state/REST/SSE, and frontend live-state behavior. docs/linting.md describes lint make commands, golangci-lint v2 intent, key linters with thresholds, and linting policy rules.
Documentation exposure and reference updates .gitignore, CONTRIBUTING.md	.gitignore unignores docs/architecture.md and docs/linting.md. CONTRIBUTING.md points readers to AGENTS.md and web/AGENTS.md for deeper conventions.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• autobrr/qui#1911: Updates to shared agent instruction documentation (AGENTS.md and CLAUDE.md) related to this PR's consolidation and restructuring of agent guidelines.

Suggested reviewers

• s0up4200

Poem

🐰 Hop, skip, and a docstring bound,
Guidelines scattered round and round,
Now neatly filed in AGENTS neat,
With web/ rules, the guide's complete!
Architecture clear, and linting's bright—
All docs in place, the path's just right. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(agents): scope agent guidance' clearly and concisely summarizes the main change: refactoring and scoping agent guidance documentation across multiple files to reduce default prompt load while preserving project guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/agents-md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}