Rethinking Team Topologies for AI-Augmented Development

One of the most significant changes in product-engineering collaboration since the advent of agile teams is happening now, driven by AI's ability to understand and act on our intent.

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 Hidden Assumptions Behind a Single File

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:

1. Experimentation phase: Single file approach wins on simplicity

2. Scaling phase: Single file becomes unwieldy, coordination issues emerge

3. Maturity phase: Context directories enable sophisticated documentation strategies

4. 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 Vision
This 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:

1. Bootstrap with single file: Start new “what if” projects with clear, simple guidance, especially if you’re using an autonomous agent

2. Evolve to context directories: Migrate to modular documentation as complexity grows

3. 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

4. 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:

1. Context organization is critical - Both approaches recognize that effective AI collaboration requires intentional context management that includes product vision, not just technical guidance

2. 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

3. Different scales require different solutions - Simple projects benefit from simple approaches; complex projects need sophisticated documentation that can evolve over time

4. Product integration is the real revolution - The ability to embed Product Vision directly into development context changes how features get built and validated

5. 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