Agentic AI documentation overhaul (mid-2026 best practices)

[ulises-c]

What this is

Sweep of agent-instruction docs across Computer-Setup and downstream
projects to match mid-2026 best practices. The AI tooling landscape
shifted through 2025–2026 (AGENTS.md cross-agent convention,
multi-agent workflows with Claude Code + opencode + Codex + Cursor,
MCP proliferation), and the docs here need to catch up.

Goals

1. Adopt the AGENTS.md convention. AGENTS.md at repo root is
   now read by Codex, opencode, Aider, Jules, Cursor agent mode, and
   Claude Code (as fallback). Tool-specific companion files
   (CLAUDE.md, future OPENCODE.md, etc.) should @AGENTS.md-import
   and only add tool-specific rules below the import.
2. Audit the global ~/.claude/CLAUDE.md. Some content here is
   project-agnostic and belongs in a portable AGENTS.md template;
   some is Claude-Code-specific (subagents, slash commands) and
   should stay where it is.
3. Codify the split rule. Project facts (architecture, build,
   conventions, don'ts) → AGENTS.md. Tool-feature usage (slash
   commands, subagents, MCP servers) → tool-specific file. If a rule
   could plausibly apply to a future agent that isn't set up yet, it
   belongs in AGENTS.md.
4. Gather learnings from other AI-heavy projects. The comment
   below captures patterns abstracted from one project
   (student-planner). Same audit needs to happen across the other
   large AI-driven projects so portable conventions get pulled out
   before they bake into the global rules.

Tools / topics to cover

1. Railguard — memory provenance warnings, append-only memory
   behavior, known false-positive patterns. See learnings comment
   below.
2. AGENTS.md — root-level placement (not .agents/), nested
   per-directory overrides (closest-file-wins like .gitignore),
   file-layout convention. student-planner has a
   docs/agents/README.md documenting the split rule and onboarding
   checklist — consider templating it for new repos.
3. CLAUDE.md — @AGENTS.md import pattern, real file not a
   symlink (Windows checkouts without Developer Mode turn symlinks
   into plain text containing the literal target string, silently
   breaking auto-load), Claude-Code-only rules below the import.
4. opencode / Codex / Cursor / etc. — confirm each tool's
   AGENTS.md support status, document config-dir patterns
   (.cursor/rules/, .opencode/, etc.). Most modern agents read
   AGENTS.md natively — only add a companion file when the tool
   genuinely needs tool-only rules.

Upstream issues and fixes needed

1. Potentially a RAILGUARD.md consolidating the safety rules and
   known false-positive patterns (see learnings comment).
2. Railguard fork PR to upstream pending — upstream may be abandoned:
   https://github.com/ulises-c/railguard

[ulises-c]

Learnings from a recent project (abstracted)

From setting up CLAUDE.md for a private project. Names and stack specifics removed; the principles are portable.

What belongs where

• CLAUDE.md = invariants. Durable rules that hold every session: how to build, where the canonical source of truth lives, architecture conventions not visible from any single file.
• Handoff docs = state. "Where we are right now" goes in date-prefixed handoffs (docs/handoffs/YYYY-MM-DD-{topic}.md), each new one superseding the previous and linking it. Keeps CLAUDE.md from rotting.
• Global rules ≠ project rules. If the global ~/.claude/CLAUDE.md covers it (comments, premature abstraction, error handling, agent triggers, bash style), don't repeat it in the project file. CLAUDE.md loads into every session's context — duplication costs tokens forever.
• Memory ≠ CLAUDE.md. Once a rule lands in CLAUDE.md, the matching memory entry becomes redundant per the memory guidance.

Patterns worth codifying in any project's CLAUDE.md

• "Source of truth" rule. When a build artifact is generated from a manifest, name the canonical input and forbid hand-editing the generated output. CI enforces drift via a diff check.
• Commit per logical chunk. Multi-topic sessions produce multiple commits.
• Never git add -A / git add .. Stage specific paths — prevents accidental commits of secrets, local tooling configs, etc.
• HEREDOC commit messages with a fixed trailer. Consistent attribution, survives shell quoting.
• "Don't fight the formatter." If the formatter rewrites naming conventions, the project style is whatever the formatter produces. State this explicitly so future-Claude doesn't re-fight it every session.
• Pure logic parameterized for testability. Free functions taking (input, deterministic-context) in a dedicated folder. Tests pin the context.
• One testing framework, stated explicitly. Pick the modern one, ban imports of the legacy one. Mixed conventions accumulate otherwise.
• --no-verify is forbidden. Pre-commit hook failures get fixed at the root cause.
• git push --force to main is forbidden.

Handoff convention details

• Filename: YYYY-MM-DD-{kebab-topic}.md — sorts chronologically, topic is greppable.
• Body structure that held up well:
  1. Pointer to the handoff it supersedes
  2. "Where we are" (last commit, status)
  3. "What landed this session" (commit-by-commit)
  4. "What's next" (table of remaining chunks + a recommended next)
  5. "Known gotchas"
• Handoffs live in docs/handoffs/, never at the repo root.

Length discipline

• Target ~100 lines for a project CLAUDE.md. Anything longer should probably be in a doc the file links to.
• Lead with a one-paragraph orientation + pointer to the latest handoff. Fresh sessions should locate current state in <30 seconds.

Candidates for the global rules file

• Handoff naming convention — currently rederived per project.
• git add -A / --no-verify / git push --force prohibitions — project-agnostic.
• A "what NOT to repeat in project CLAUDE.md" section so future projects don't re-import what's already global.

Railguard observations

Railguard enforces safety rules on the memory store and on destructive actions. A few things worth codifying:

• Memory is append-only. Agents can't delete memory files even when their contents are superseded (e.g., a rule that has since landed in CLAUDE.md). Workaround: leave the file in place, or surface the redundancy to the user for manual removal.
• Provenance / integrity warnings can appear at session start for untracked memory files. Informational, not blocking.
• False positives exist. Pattern-based blocks can trigger on benign content — for instance, writing the literal string railguard inside a Bash HEREDOC may be blocked even when the operation is harmless or you're explicitly working on Railguard itself.
  • Workaround: prefer the dedicated Write / Edit / Read tools over Bash for file content. The match runs on the Bash code path; writing through structured tools sidesteps it cleanly.
  • This is not a license to evade legitimate rules — only to avoid spurious pattern matches on content that has nothing to do with destructive actions.

How Claude should handle Railguard:

• Default: respect the rules. Don't attempt workarounds when a block is doing its job.
• For obvious false positives (e.g., the HEREDOC pattern above), switch tools and proceed — don't pester the user.
• For genuine bugs in Railguard, flag to the user — don't try to fix Railguard inline. The upstream fork is where real bugs get patched.
• A future RAILGUARD.md in Computer-Setup will likely consolidate this guidance; check there first.