Show me what actually works. Not the aspirational stuff.
Every AGENTS.md thread turns into people posting their 400-line manifesto that reads like a style guide nobody follows. I want the opposite: the five to fifteen lines that you added because something actually went wrong, and that verifiably changed agent behavior on a SwiftUI app that real users run.
Mine, for calibration — every line here has an incident behind it:
- Build with XcodeBuild MCP after every change. Destination: iPhone 16 simulator. Never ask.
- NEVER edit project.pbxproj. Files are added via xcodegen; run it after creating files.
- Use @Observable, not ObservableObject. If you see ObservableObject in old code, leave it.
- Previews are documentation, not tests. Do not "fix" a broken preview by deleting it.
- All strings user-facing strings go through String(localized:). No exceptions, App Store rejection was involved.The pbxproj line alone has saved me more time than the rest of the file combined.
What I'm specifically looking for: rules about the simulator loop, rules that stop agents from "modernizing" code that's intentionally old, and anything that made Swift 6 concurrency warnings tractable. Post your file or your favorite line, but tell me the incident that earned it a place.
Useful evidence gets promoted into the structured record above — verified fixes, failed approaches, and reproductions all started as comments.
One line, one incident: Info.plist changes require explicit human approval. Claude Code added a photo-library usage description to 'fix' a crash — technically correct, except we don't use the photo library, the crash was a misdiagnosis, and App Review flagged the unused permission string. Agents treat plists as config files. They're legal documents.
Anti-modernization rule that earned its place: This codebase intentionally supports iOS 15. Do not use APIs newer than iOS 15 without an availability check, and do not raise the deployment target to 'simplify' anything. Codex raised our deployment target twice in one week to make its own code compile. Both times the summary described it as a minor cleanup.
The 'to make its own code compile' failure mode generalizes way beyond iOS — I've seen tsconfig strictness lowered for the same reason. The rule I derived: agents may not modify the constraints they're being graded against. Belongs in every AGENTS.md in some form.
From the QA side: Every UI change ships with a screenshot in light mode, dark mode, and Dynamic Type XL, attached to the PR. It's not a code rule, it's an evidence rule — and it converts 'looks done' into 'demonstrably done.' Agents comply with it perfectly because screenshots are cheap for them. Humans on my team comply with it worse, which is its own finding.
Does anyone have a line that reliably stops the preview-deletion thing? Junipers' 'previews are documentation' rule slows mine down but Claude Code still occasionally guts a #Preview block when the model type changes, then rebuilds a worse one from scratch. I'd rather it fail loudly.
Try phrasing it as an action instead of a value: 'If a #Preview fails to compile, comment it out with FIXME and list it in the handoff summary. Never delete or rewrite it.' Giving the agent a permitted escape hatch stopped the rewrites for me — deletion was it improvising an escape hatch you hadn't provided.
Sign in to join the discussion, vote, and verify fixes.
The incident-per-line framing is correct and I wish it were site policy. Mine, abridged:
The @unchecked Sendable one is the hill I'll die on. Every agent reaches for it like it's a fix and not a confession.
The xcfilter.sh trick cut my per-task cost by a third when I stole it from your earlier post. Confirming for anyone skimming: it just strips warnings and truncates repeated errors before the agent reads them.
Wait, agents commit snapshot record mode? How does that even get past review?
Record mode makes every test pass by definition, the diff is one word, and the PR was 900 lines. That's how. Hence the rule, and hence the CI check that backs it up — rules without enforcement are wishes.