Software development has changed, and it's exciting. We need to address how our team structures need to evolve alongside these revolutionary tools. There's a perceived (or at least hype-marketed) shift from "how to code" to "how to prompt" and that's of course nonsense. In my opinion, you still need to understand architecture and practices to produce production-ready and secure code. You might have heard anecdotes or have tales from your own experience that contradict this, but either way, it begs a fundamental reconsideration of how we organize our development teams.
This isn't a revolutionary thought. The emergence of AI-first development approaches is producing concrete implementations, each of them at least slightly aspirational and revealing both the potential and limitations of different models.
The Evolution of Development Team Structures
For the uninitiated, software development organization has evolved through distinct phases over the decades:
Waterfall (1970s-1990s): Specialized roles with sequential handoffs
Agile teams (2000s): Cross-functional squads with iterative delivery
DevOps (2010s): Breaking down the dev/ops divide
Platform teams (Late 2010s): Internal platforms serving product teams
AI-augmented devs and teams (Now): Context-driven structures with human-AI collaboration
Each evolution responded to specific constraints and opportunities of its era, primarily the limits of human coding capacity and communication overhead, not to mention change management. Conway's Law has shaped these structures, with system designs reflecting organizational patterns of communication and function.
Flash forward to now, and generative AI fundamentally changes the equation by both adding and removing variables. When a single developer (or Idea Person at this point) with an AI assistant can produce what previously required a small team, at minimum to create a prototype but potentially a release candidate, the constraints shift dramatically. We're moving from reviewing lines and pull requests to whole system design in as few as one person’s hands, a transition the prior team structures weren't designed to handle.
Context File vs. Context Directory
Two distinct approaches to AI-augmented development are already emerging in practice, each reflecting different philosophies about how teams should organize context for AI collaboration. (Spoiler: I have a favorite, and it’s not the popular one.)
The Single File Approach: Centralized Context
OpenAI’s Codex presents one such model, a single AGENTS.md file per project with:
Project structure and architecture guidelines
Coding standards and style conventions
Testing frameworks and requirements
Pull request message formats
Security and compliance requirements
This single file sits in the repository root (or additional such files at directory/subdirectory levels with hierarchical precedence) and serves as the primary interface between human intent and AI implementation. But even without Codex or similar, you can provide that file as instructions for a non-autonomous, IDE-embedded agent, and provide base-level instructions for precedence.
The strength of this approach lies in its simplicity and immediacy, as well as conservation of tokens for the actual heavy lifting of AI-assisted development. A pretty nice way to fork your instructions for new features in their new directories, too. These files' scope can include the files it's modifying, applies the instructions to format, test, and document its changes, and prioritizes deeper nested instructions when multiple files apply. For autonomous coding agents working in sandboxed environments, this provides clear, discoverable guidance. Pretty revolutionary.
Distributed Knowledge: The Context Directory Approach
My preferred alternative for IDE use is one that I gravitated toward in working with Claude Code, and uses multiple documents in a /context directory structure at the project root:
/context/├── api-documentation.md├── architecture-decisions.md├── business-requirements.md└── diagrams/ ├── data-flow.png └── system-architecture.svg├── system-overview.md├── technical-requirements.md├── working-style-guide.md
N.B.: If interested in what I put into each such file, contact me!
In this model, each document serves a specific purpose and can evolve independently. This should be pretty familiar to anybody who’s worked on structured projects with stakeholders. Related, I’ve found it a good idea to review each periodically to make sure the distributed guidance is being kept in sync. Rather than a single file containing all guidance, though, this approach separates concerns: architectural decisions remain stable while prompt templates adapt to new AI capabilities. And aside from manual review, when I’m making a change that I just know would impact one of the original documents, I have the AI edit that as well, and review all changes prior to commit to repo.
Single Files Are More Prevalent
Right now, it looks to me that emerging practices heavily favor single file approaches, and AGENTS.md, context.md, LLM.txt, and others are among the things I’ve seen in the wild with or without autonomous agents. (What monster doesn’t use Markdown, though??) There are specific technical reasons why single files approaches are gaining momentum, aside from the fact that it works quite well for idea-to-prototype in a single developer environment.
What Makes Single Files So Effective
Zero “Cognitive Load” for AI Agents: An AI agent encountering a repository doesn't need to make decisions about which documents are relevant. Everything it needs is in one discoverable location. This eliminates the complexity of understanding information architecture.
Atomic Context Loading: AI agents can load all relevant context in a single read operation. No need to traverse directories, understand relationships between documents, or piece together information from multiple sources.
Hierarchical Override System: Applyiong hierarchy to the approach creates a predictable cascading configuration system. Root-level guidance provides defaults, while subdirectory files offer specific overrides. AI agents can apply this precedence without complex reasoning. (Though I wonder how many people see that “just put another file in the new directory” instruction and remember what it was like to use SVN before Git took over…)
Proven Effectiveness with Autonomous Agents: It’s been demonstrated to work remarkably well when agents operate independently in sandboxed environments. The single file provides complete context without requiring sophisticated reasoning about information architecture.
Tool Independence: Any AI system can consume a single human-readable file. You're not dependent on sophisticated context discovery capabilities or specific integration features.
The current promotion of single files is based on specific assumptions that aren't always made explicit:
AI agents are the primary consumers of the documentation
Projects remain relatively simple and well-bounded
Context doesn't need to evolve at different rates across different domains
Teams don't need rich collaboration around documentation
All stakeholders (AI agents, developers, product managers, architects) have the same information needs
These assumptions hold true for many current AI-augmented development scenarios, which is why the single file approach feels like such a universal tool.
When Single Files Hit Their Limits
Monolithic Growth: As projects mature, that single file becomes unwieldy. You end up with a 500-line file that's difficult to navigate for both humans and AI agents. The “cognitive load” that was eliminated for AI agents gets transferred to human maintainers. It’s a slog to hunt & peck in huge files.
Change Coordination Friction: When multiple people need to update different aspects of context, they're all editing the same file. This represents coordination overhead that can slow down development velocity.
Mixed Audience Optimization: Product managers need different information than infrastructure engineers. AI agents need different formatting than human architects. Single files may eventually force you to optimize for one audience at the expense of others.
Evolution Rate Mismatch: Architectural decisions might be stable for months, while prompt templates need weekly refinement. Testing frameworks evolve differently than coding standards. Single files make it difficult to manage these different rates of change.
Simplicity vs. Sophistication
The single file vs. multiple files debate isn't really about which approach is "better", but about optimization for different stages of project and team evolution.
Single Files Are Optimized For:
Getting started quickly - Zero setup, immediate AI effectiveness
Autonomous AI workflows - Agents working independently without human oversight
Simple to moderate complexity - Projects that fit comfortably in one mental model
Small, co-located teams - Minimal coordination overhead for documentation changes
Standardization across projects - Consistent patterns that scale horizontally
Context Directories Are Optimized For:
Long-term sustainability - Documentation that grows and evolves with the project
Cross-functional collaboration - Multiple stakeholders contributing different expertise
Complex enterprise systems - Rich architectural context and multi-domain knowledge
Distributed teams - Parallel documentation work without merge conflicts
Advanced AI integration - Supporting multiple AI tools with different context needs
Think of it as the difference between a Swiss Army knife and a toolbox. The Swiss Army knife (single file) is incredibly convenient and handles most situations well. The more heavily-equipped toolbox (context directories) requires more setup and organization, but enables capabilities and scalability that a single-file approach simply can't match.
Why This Matters for Your Strategy
The single file is actually advice optimized for a specific scenario: teams experimenting with AI-augmented development on relatively simple projects, including Codex-style automations and similar. This describes a lot of current AI adoption, which is why the advice feels universal.
But as AI-augmented development matures, teams hit the limits of single files:
Projects grow beyond what one file can reasonably contain
Multiple stakeholders need to contribute context (imagine merging Marketing into this engine…)
Different types of context need to evolve at different rates
Teams need to serve both AI agents and human understanding
The sophistication curve looks like this:
Experimentation phase: Single file approach wins on simplicity
Scaling phase: Single file becomes unwieldy, coordination issues emerge
Maturity phase: Context directories enable sophisticated documentation strategies
Enterprise phase: Hybrid approaches serve multiple stakeholders effectively
Breaking Down the PRD Wall: The Real Revolution
Here's where this gets really interesting to me, and where both approaches represent something much bigger than just organizing technical documentation. Meaning, no matter what flavor/shade of the above you use, there are significant gains.
Both single file and context directory approaches are fundamentally changing how Product Vision flows through the development process. There's traditionally been a proverbial "wall" between PRDs with Product Vision and the rest of the development process, sometimes reminiscent of waterfall approaches and even in agile organizations.
This wall manifests as:
Information access barriers where developers can't easily access original PRDs, user research, or competitive analysis
Temporal disconnects wherein PRDs become historical artifacts by the time development begins
Organizational handoffs where product context stops flowing at defined boundaries
Translation loss through multiple requirement transformations (PRD → User Stories → Tech Specs → Implementation)
An Integration
Both context approaches enable something revolutionary: embedding the aforementioned Product Vision directly into the development context. I’m not the first to write about this phenomenon , and you should seek out some other opinions on it. Below is how I see it, though.
Traditional Flow:
PRD → User Stories & Technical Specs → Development → Validation
AI-Augmented Flow:
PRD + Technical Context → Continuous Development & Validation → Iterative Vision Refinement
Now when agents implement features - human-assisted or not - they can validate against the original product vision, not just technical specifications. The question shifts from "Does this code meet the technical spec?" to "Does this implementation serve the original user need and business objective?" If that sorts of sounds like a big part of a product manager’s gig, you’re starting to get it.
Single File and PRD Integration
With the single file model, product requirements can be directly embedded:
# AGENTS.md
## Product VisionThis feature enables sales teams to prioritize leads based on conversion probability, increasing qualified pipeline by 25%.
## User Experience Requirements- Response time under 200ms for scoring requests- Confidence scores visible to users with explanations- Integration with existing CRM workflows
## Technical Constraints- Must work with existing Salesforce integration- Compliance with regulatory requirements (PCI DSS, SOC2)- Gradual rollout capability required
## Success Metrics- Lead conversion rate improvement- Sales team adoption rate- System performance benchmarks
Context Directory and PRD Integration
The context directory model enables even richer product integration:
/context/├── competitive-analysis.md # Market positioning├── product-vision.md # Core product strategy├── success-metrics.md # How we measure product success├── technical-requirements.md # Engineering constraints├── user-research.md # Research findings and user needs └── user-stories/ # This is no time to ├── crm-integration.md # argue the value └── sales-lead-scoring.md # of user stories...
This allows each distinct product-relevant context to evolve independently while remaining accessible throughout development. And, most importantly, referenceable.
Success Criteria, Too…
This integration pattern can also enable definition of the long-tail of success metrics. Product requirements can be expressed as testable criteria that both humans and AI agents can validate against, throughout development and then after implementation:
## Product Success Criteria- [ ] Sales users can score leads in under 3 clicks- [ ] Confidence explanations are understandable to non-technical users - [ ] Integration preserves existing CRM workflows- [ ] Lead conversion rate increases within 30 days of deployment
Getting really fancy about it, AI agents can implement features while continuously checking these criteria, ensuring technical implementation actually serves user needs.
When Each Approach Works Best
Single File Excels For:
Autonomous AI agents: When AI works independently without human oversight
Rapid prototyping: When speed of setup matters more than sophistication
Simple projects: When project complexity remains manageable
Immediate deployment: When you need AI guidance working immediately
Team standardization: When enforcing consistent practices across one or more projects
Context Directories Excel For:
Complex enterprise projects: When architectural sophistication matters
Evolving systems: When different aspects of the project change at different rates
Team collaboration: When multiple people contribute to documentation
Long-term maintenance: When projects will evolve over years
Rich product integration: When product vision needs sophisticated documentation
Hybrid Approaches: Best of Both Worlds
Some teams are beginning to combine approaches:
Bootstrap with single file: Start new “what if” projects with clear, simple guidance, especially if you’re using an autonomous agent
Evolve to context directories: Migrate to modular documentation as complexity grows
Generate the single agent file from context: If you’re backing into adding an agent, automatically create (and manually review) their “master file” from context directories
Maintain dual interfaces: Keep both simple AI guidance and rich human documentation
This hybrid approach acknowledges that different stakeholders - autonomous AI agents, human developers, product managers, and system architects - need different interfaces to the same underlying knowledge.
Choosing Your Context Strategy
Organizations should consider their specific circumstances:
Start with a single file if:
You're experimenting with AI-augmented development
Your projects are relatively simple or well-bounded
You want immediate results with minimal setup
Your team is small and co-located
You're using one or more autonomous AI agents
Start with Context Directories if:
You're planning for complex, long-term projects
Your team already has strong documentation practices
You expect significant architectural evolution
You have distributed teams needing rich context
You want deep product-engineering integration
Consider a Hybrid Approach if:
You have a mix of project types and team structures
You want to experiment while maintaining sophisticated documentation
You're building platform teams that serve multiple product teams
You need to balance immediate AI effectiveness with long-term maintainability
So What Now?
The emergence of different context management approaches reflects the broader challenge of organizing teams for AI-augmented development. But more fundamentally, both approaches break down that “wall” between Product Vision and implementation that has plagued software development for, it seems, forever. (Or at least as long as I can remember.)
While the disruption is relatively new, I’ve found these insights useful:
Context organization is critical - Both approaches recognize that effective AI collaboration requires intentional context management that includes product vision, not just technical guidance
The PRD wall can finally be broken - AI agents and developers can now work directly with Product Vision rather than translated requirements, fundamentally changing product-engineering collaboration; more importantly, Product Managers are in the flow
Different scales require different solutions - Simple projects benefit from simple approaches; complex projects need sophisticated documentation that can evolve over time
Product integration is the real revolution - The ability to embed Product Vision directly into development context changes how features get built and validated
Hybrid strategies offer flexibility - The most sophisticated teams combine multiple approaches to serve different stakeholders effectively
The most successful organizations won't be those that simply adopt AI coding tools - they'll be those that thoughtfully organize context to enable effective human<>AI partnerships while keeping Product Vision central to implementation decisions.
The future belongs to devs and teams that can maintain human touch while enabling AI tools to contribute effectively in service of user needs. The context organization strategy you choose will determine how successfully you and your teams navigate their transition.
CREDITS: Cover image by OpenAI Sora; Claude Sonnet 4.0 for editorial review