Context is the new hard problem in software development. AI agents can write code, but they often lack the historical, architectural, and human context that...
Context Is the New Hard Problem in Software Development
Context is the new hard problem in software development. AI agents can write code, but they often lack the historical, architectural, and human context that explains why systems behave as they do, and that gap breaks things fast. That's the blunt truth. — Ernie Castro
Key Takeaways:
- Context is the collection of facts, decisions, and history behind a system.
- AI code generation solves syntax and patterns, not the reasons for decisions.
- Use architecture decision records (ADRs), knowledge bases, runbooks, and observability to encode context.
- Treat context as a first-class artifact in repositories and CI/CD.
- Small, consistent stewardship yields big stability wins.
What is Context?
Context is the set of reasons, records, and real-world constraints that explain why software behaves a certain way. I have rebuilt microservices where the code worked, but the system still failed under load because crucial config choices were undocumented. I once patched a production bug in an hour, and then found out three months later the change violated a compliance rule—because no one had written down the rationale. Context includes things like requirements, assumptions, ADR files, operational runbooks, telemetry dashboards, and stakeholder agreements. When I worked at Google, we logged rationale in ADRs and linked them from PRs, and that practice prevented a bad refactor from cascading into a week-long outage. People say documentation is dead. I disagree. Good context is stewardship of shared knowledge, and it honors the dignity of work by reducing waste and rework.
Core Benefits/Importance
Clear context leads to faster incident resolution. When team members have accessible runbooks and logs, they resolve outages faster. Better code reviews follow when PRs include ADR links and concise reasons, because reviewers stop guessing about intended behavior, and reviewers can ask technical questions grounded in historical trade-offs. Safer automation happens when CI/CD enforces context checks so unsafe changes fail fast. Preserving tribal knowledge with searchable knowledge bases keeps facts from vanishing when someone leaves, and that reduces risky guesswork. Recording decisions is an ethical act; it preserves human dignity by reducing toil and harm to users. I once joined a small startup where no one recorded why a feature was disabled in production. That lack of context meant developers rolled back a security fix two weeks later, causing harm. If we care about stewardship and justice, we document, and we use tools to keep facts honest.
Step-by-Step Implementation/Guide
Start with ADRs. Create a short template and require an ADR for significant design or configuration changes. I made ADRs mandatory on one team, and the number of avoidable rollbacks dropped sharply. Link ADRs in PRs and commit messages so reviewers can find the rationale without digging through chat logs. Build a searchable knowledge base with tags for systems, owners, and topics like "performance" or "compliance." Enforce context checks in CI to fail builds when ADRs or runbooks are missing for risky changes. Store operational runbooks alongside code and keep playbooks for common incidents; I once fixed a cascading outage using a runbook written the week before, and that saved hours. Improve telemetry and dashboards so why-facts surface early and teams can correlate behavior with decisions. Rotate ownership and review context artifacts yearly so they stay current and accurate. Remember: this is a cultural practice more than a tooling fix. Tools help, but they do not replace the moral choice to treat knowledge as a shared good.
Comparison Table
Below is a quick comparison between a context-first approach and a code-generation focus.
| Feature | Context-first approach | Code-generation focus |
|---|---:|---:|
| Primary output | **Rationale and records** | Generated code snippets |
| Long-term stability | High when cared for | Low without context |
| Onboarding speed | Faster with ADRs and KBs | Slower if only code exists |
| Incident resolution | Quicker with runbooks | Slower without human notes |
| Compliance readiness | Better if decisions logged | Risky without records |
Common Mistakes to Avoid
Most guides say "document later," but that advice often leads to trouble. I once followed the "document after" rule and we lost an entire sprint because the person who knew the trade-offs left the company. Common traps include writing fluff instead of clear reasons, keeping docs in private drives where teammates cannot find them, treating ADRs as bureaucratic checkboxes, and relying solely on code comments that lack context. Be skeptical of quick fixes that promise immediate wins with no follow-up. Real context requires discipline and modest effort. The dignity of work means we preserve knowledge for colleagues and users, and making ethical choices about who can access or edit context artifacts is part of that responsibility. Small acts of stewardship compound into dependable systems.
Frequently Asked Questions
- Q: Can AI agents capture context?
A: AI can summarize docs and draft context artifacts, but without source truth and human review the summaries miss critical nuance. See examples from OpenAI Codex and GitHub Copilot.
- Q: Where should context live?
A: In version-controlled repos, linked ADRs, and searchable knowledge bases tied to the code and CI/CD pipelines. See ADR best practices at adr.github.io.
- Q: Is documenting context heavy bureaucracy?
A: No. Lightweight ADRs, short runbooks, and simple CI checks are practical and pay back quickly. Observability articles from Honeycomb show why telemetry matters for context.
- Q: How fast will this help?
A: Expect measurable benefits within weeks if you require ADR links in PRs and add CI checks; long-term cultural effects take months.
Final Thought
Record the why. I learned that the hard work of software is rarely typing lines; it's preserving understanding for the next steward. When I started at my first big company, I thought speed was the virtue. Years later, after outages and long nights, I value careful records more. That practice is small stewardship, and it fits a moral view of work: we leave things in better shape for those who follow. — Ermenildo V Castro