What Agents Can Infer Versus What They Need
Code patterns agents detect automatically; implicit vs explicit context; when documentation is essential
Given what agents can see, what can they reliably figure out on their own and what requires explicit documentation?
Too little context leads to incorrect assumptions. Too much dilutes signal. The distinction matters.
What agents infer reliably
Agents excel at extracting information that's directly visible in code:
- Dependencies Framework versions, testing libraries, build tools. Reading
package.jsonorrequirements.txttells them everything they need. - Code patterns Import conventions, async styles, error handling approaches, naming conventions. Agents mirror what they see.
- Test structure Frameworks, assertion styles, mocking patterns. Well-written tests teach quality standards implicitly.
These capabilities require no documentation. If it's in the code, agents will find it.
The inference boundary
Agents detect what is present. They struggle with what is absent, implicit, or external to the repository.
A 2025 industry survey found that 65% of developers report AI missing relevant context during refactoring. The gap is almost always domain knowledge that can't be extracted from code.
Consider four scenarios where code tells an incomplete story:
The $10,000 rule. Your checkout has special handling for large orders approval workflows, fraud checks, different processors. The code shows conditional logic at a threshold. It doesn't explain the regulatory requirements, fraud patterns, or why this specific number. Without documentation, an agent might "simplify" this away.
The forbidden library. The team tried fast-json-parser in 2023. Memory leaks under load. Everyone uses json-stream now. The code shows current imports. It doesn't show the incident, the decision, or the reasoning. An agent optimizing for performance might recommend the forbidden option.
The API that lies. The payment sandbox returns 200 OK for everything. Production rejects malformed requests with cryptic errors. The code shows robust error handling. It doesn't explain which edge cases came from production incidents.
The security gate. Auth changes require security team sign-off before merge. Not enforced by CI it's team process. The code shows module structure. It doesn't indicate review triggers or approval flow.
The new hire mental model
Every agent session starts fresh like a new hire who read all the onboarding docs but has zero institutional memory.
| What this hire knows | What this hire lacks |
|---|---|
| Languages and frameworks in the repo | Why that pattern exists in legacy/ |
| Repository structure and navigation | The outage caused by that "optimization" |
| Documented conventions | Which reviewer cares about which style |
| How to write syntactically valid code | Verbal agreements about architecture |
| Framework idioms and best practices | What approaches were tried and failed |
Unlike humans who accumulate knowledge over time, agents reset to baseline each session. A mistake corrected Monday will recur Wednesday unless you add it to CLAUDE.md.
What requires explicit documentation
Four categories consistently fall outside the inference boundary:
| Category | Examples |
|---|---|
| Domain rules | Order thresholds, prohibited combinations, customer tier logic, regulatory requirements |
| Architectural decisions | Why this pattern was chosen, which constraints drove it, what alternatives failed |
| Tooling preferences | Preferred libraries, build commands with specific flags, CI/CD expectations |
| Institutional memory | Past failures and why, technical debt plans, deprecated patterns to avoid |
Practical implications
Verify assumptions early. When tasks involve business logic, architectural decisions, or external integrations, ask: "What assumptions are you making about X?" Assumptions surfaced early cost minutes to fix. Assumptions embedded in code cost hours.
Document at the point of confusion. When an agent makes an incorrect assumption, the immediate fix is correction. The durable fix is adding that knowledge to CLAUDE.md so it never happens again.
Focus on the delta. Standard programming practices don't need explanation async/await works the same everywhere. Document what's specific to this project: the business rules, the history, the team conventions that differ from defaults.