# Agent Loop Feedback Reference When the code under review was generated by an AI agent, recurring mistakes are not just *code* problems — they are *instruction* problems. This document defines how the reviewer aggregates per-finding signals into rule suggestions that can be added to `.claude/CLAUDE.md` or an agent system prompt to prevent the same class of issue next time. --- ## 1. The ≥2 Threshold A single instance of a mistake is a slip. Two is a pattern. Three or more means the agent's instructions are silent on the topic and need an explicit rule. Rules of thumb: | Occurrences in diff | Treatment | | ------------------- | --------------------------------------------------------------------------------- | | 1 | Per-file finding only. Do not surface in Agent Loop Feedback. | | 2 | Recurring pattern. Suggest a rule. Mark priority **medium**. | | 3+ | Strong signal. Suggest a rule. Mark priority **high**. | | 2+ across PRs | If the same rule has been suggested before (see §3), escalate to **high**. | Count occurrences by **rule**, not by raw findings. For example, four force-unwrap findings in different files count as four occurrences of the rule *"never force-unwrap"*, not four separate rules. --- ## 2. Phrasing Rules as Directives Rules go in an instruction file the agent will *read*. Write them so the reader knows what to do without further interpretation. ### Strong forms - **Never X.** — bans an action outright. Best for safety/security/crashes. - **Always Y.** — mandates an action. Best for required patterns. - **Prefer X over Y.** — gives a default with an implicit escape hatch. Best for stylistic or modernization rules. - **Use X. Y is deprecated / forbidden.** — adds the *why* in five words. ### Weak forms (avoid) - **"Try to..."** — agents will skip it under pressure. - **"It's a good idea to..."** — descriptive, not directive. - **"Consider..."** — fine in code review prose, useless as a rule. - **"X is bad"** — diagnostic, not prescriptive. Doesn't tell the agent what to do instead. ### Examples | Weak | Strong | | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | Force unwraps are dangerous. | Never use `!`, `try!`, or `as!`. Use `guard let` with an early return, typed throws, or `as?`. | | It's better to use `NavigationStack`. | Use `NavigationStack` exclusively. `NavigationView` is deprecated as of iOS 16. | | Try to keep views simple. | Views must not contain business logic, network calls, or data transformations. Move all such work into the `@Observable` view model. | | Make sure UI updates happen on the main thread. | Always annotate types that mutate `@Observable`/`@Published` state with `@MainActor`. | | Don't put secrets in logs. | Never log values from `KeychainService`, `URLRequest.httpBody`, or types annotated `@Sensitive`. | A good rule answers three questions in one sentence: *what is forbidden*, *what is the alternative*, and (briefly) *why*. --- ## 3. Checking Past Reviews Before suggesting a rule, check whether something similar was already suggested. If yes, the existing wording is not landing — escalate priority and consider strengthening the wording rather than restating it. ```bash # Has anyone touched the rules file recently, and how? git log --oneline --follow .claude/CLAUDE.md git log -p --follow .claude/CLAUDE.md | grep -i "" # Search for existing wording on the topic grep -in "force.unwrap\|navigationview\|mainactor" .claude/CLAUDE.md ``` If a rule on the same topic exists: 1. Quote the current rule in the suggestion block. 2. Explain why it is not preventing the pattern (too soft, too narrow, buried, conditional). 3. Propose a replacement, not an addition. If no rule exists, propose adding one in the most relevant section (`Concurrency`, `SwiftUI`, `Security`, `Architecture`, etc.). --- ## 4. Suggested-Rule Block — Template One block per recurring pattern. Place all blocks under a single `## Agent Loop Feedback` heading at the bottom of the report. ```markdown ### Pattern: ( occurrences) **Files**: , , ... **Suggested rule**: > instead, and one-clause why.> **Existing rule** (if any): **Why it's not landing** (only if existing rule): **Priority**: ``` Worked example: ```markdown ### Pattern: Force-unwraps (4 occurrences) **Files**: LoginView.swift:89, NetworkService.swift:34, UserRepo.swift:12, UserRepo.swift:78 **Suggested rule**: > Never use `!`, `try!`, or `as!`. Use `guard let` with explicit early return, > typed throws, or `as?` with handling. Force-unwraps are crashes waiting to happen. **Existing rule**: _.claude/CLAUDE.md:42_ — "Avoid force unwrapping when possible." **Why it's not landing**: "When possible" gives the agent a built-in opt-out. The replacement above bans the syntax outright and names the alternatives. **Priority**: high ``` --- ## 5. Human-Authored Code If the PR was written by a human (no AI assistance disclosed, no agent session metadata in commit messages), the same recurring patterns are still useful — but frame them as **team coding standards**, not agent instructions: - Replace "Suggested rule for the agent" with "Suggested team standard". - Drop the "Why it's not landing" clause; humans benefit more from a short rationale than from instruction-tuning analysis. - Leave the directive phrasing intact — strong forms read better in human style guides too. When unsure whether the code is AI-generated, default to the team-standards framing.