docs: add review guidelines and feedback routing for agents

[Reefact]

Summary

Add repository guidelines that steer automated agents: how an automated reviewer (for example Codex) must format and select pull request review comments, and how the agent that fixes a pull request responds to that feedback. No library or user-facing behavior changes.

Type of change

• Bug fix
• New feature
• Breaking change
• Refactoring
• Analyzer / diagnostic change
• Tests
• Documentation
• Build / CI / tooling

Changes

• Add code_review.md: the full Conventional Comments specification for pull request reviews — comment format, labels, decorations, blocking rules and finding selection — with examples grounded in this repository's API (Outcome, ErrorCode.Create, ErrorContext, GenDoc, the FCExxx analyzers).
• Add AGENTS.md: the entry point for automated agents — project orientation, a mandatory inlined subset of the review rules, and a "Responding to review feedback" section that routes disagreements and human-judgement calls to @reefact and caps bot re-review cycles.
• Link CLAUDE.md to the "Responding to review feedback" rules, with the essentials inlined so they bind the acting agent even if AGENTS.md is not read.

Testing

• dotnet build FirstClassErrors.sln
• dotnet test FirstClassErrors.sln
• Analyzer tests pass (FirstClassErrors.Analyzers.UnitTests)

Docs-only change — no build or test surface is touched, so the commands above were not run. Both commit messages were validated with tools/commit-lint/lint-commit-message.sh (the same check CI runs on every pull request).

Documentation

This pull request is itself contributor/agent-facing documentation and changes no user-facing behavior, so no README or French translation (doc/README.fr.md) update is required.

Related issues

None.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01XAzVV5kTFuoTABDYZHSKR1

---

Generated by Claude Code

[Reefact]

@codex Any thoughts about that ?

[chatgpt-codex-connector]

Thoughts

I do not see a blocking issue in the PR content from the context available here. The added guidance is coherent and internally consistent:

• AGENTS.md clearly separates repository orientation, review-comment rules, and acting-agent feedback routing. It also explicitly says the fuller review specification lives in code_review.md. AGENTS.mdL21-L24
• The inline review format rules are strict enough to prevent the common failure modes: unlabeled comments, multiple findings in one comment, severity prefixes, and repeated findings. AGENTS.mdL28-L44
• The label defaults and allowed decorations are documented in both the short inlined form and the full guide, including the important rule not to restate default blocking/non-blocking status. AGENTS.mdL58-L75
• The “Responding to review feedback” section gives a clear escalation path: fix clear local findings, route disagreements to @reefact, and avoid bot-to-bot argument loops. AGENTS.mdL98-L123
• CLAUDE.md links back to the same feedback-routing rules and inlines the essentials, which is useful because Claude-specific agents may read that file before AGENTS.md. CLAUDE.mdL80-L93

The only minor thought I had is non-blocking: the template syntax <label> [(decorations)]: <subject> could be read literally as including brackets, but the examples immediately clarify the intended syntax, so I would not request a change for that. code_review.mdL16-L24

No code or documentation changes were necessary, so I did not commit or open a follow-up PR.

Checks

• ✅ pwd && rg --files -g 'AGENTS.md' -g 'code_review.md' -g 'CLAUDE.md' && git status --short && git log --oneline -5
• ✅ sed -n '1,220p' AGENTS.md && sed -n '1,260p' code_review.md && sed -n '1,220p' CLAUDE.md
• ✅ git diff --stat 346ae49..HEAD && git diff --name-only 346ae49..HEAD && git diff 346ae49..HEAD -- AGENTS.md CLAUDE.md code_review.md
• ✅ nl -ba AGENTS.md | sed -n '1,135p'; nl -ba code_review.md | sed -n '1,80p'; nl -ba CLAUDE.md | sed -n '80,115p'; git status --short

View task →

[Reefact]

Thanks for the read. The single non-blocking point — that the [(decorations)] / [discussion] template could be read as if the square brackets were literal — is addressed in 4b3f663: both AGENTS.md and code_review.md now state that < > is a placeholder and [ ] marks an optional part, with decorations written in parentheses. Nothing else required a change, so the discussion is resolved on our side.

---

Generated by Claude Code