Context Architecture - Aligning Humans and Agents at Scale

I've previously shared my vision that the industry is moving towards software factories for 99% of code changes and to make that effective we'll need to move to a paradigm of Durable Context and Disposable Code.

The next bottleneck to actually implement this is Alignment - how do we align humans and agents at scale - across organization, agent swarm, codebase, and concurrent project sizes - so we can actually speed up the full SDLC. Here we'll discuss an approach I've been experimenting with at work and in my side projects - Context Architecture.

Alignment is the Bottleneck

Organizations have long struggled to align humans at scale. We created processes to manage this like waterfall and agile, docs for alignment like PRDs/RFCs, products like task trackers and knowledge bases, and various organizational structures from top down to bottom up.

I'd even posit that types in programming languages are their own form of context alignment.

This is one reason so many thought AI would have a minimal impact on the industry - 60% of your time is spent on alignment, only 20% on coding and a 20% speedup isn't that big of a deal. But as we've seen AI has and is rapidly changing the state of the industry (I'm personally seeing close to 2x throughput).

This alignment bottleneck becomes more acute in the age of agents as we add an additional hop to our game of telephone.

• Previously: Human to human -> artifact
• Now: Human to human -> human to agent -> artifact
• Near future: Human to human -> human to agent -> agent to agent -> artifact

As we move to agents managing agents and full software factories, we need better ways to align at scale.

So the goal of the Context Architectures I'm proposing is to align humans and agents at scale. To get there I have a few sub areas I'm focusing on:

• Context Discovery - Provide the right information at the right time while minimizing noise from information you don't need
• Context Authority - A single source of truth for each bit of context to avoid conflicting guidance
• Context Change - Provide a means to experiment, promote, and maintain standards across teams and orgs
• Context Maintenance - Straightforward to maintain and prevent bitrot and stale guidance, esp as change happens faster than ever

Context and Information Architecture

The way I've been thinking about approaching this is through the jobs we're typically trying to do and the constraints we're under.

The first kind of context is providing guidance on how to do certain things - think runbooks, best practices, and available tools. This is one of the most common pieces of information at any org and is typically the ones that are more up-to-date as they get more foot traffic (and thus complains when they don't work). For these I think we use agent skills - a toolbox for how to do common things.

The next is explaining why a system exists, what it does, and how it does it along with additional info around maintaining it. In the past this context typically incurs bitrot as there was no single source of truth - it was scattered around in various docs, task trackers, people's heads, and often in various bug fixes and requirement changes only present in git, code comments, or if more disciplined test cases. Moreover this context was often only maintained by a single team and the effort of maintaining it usually deferred until the next project that had to touch a certain area. As the need to align (and penalty for not doing so) grows I think we need to move this information into a more sacred source of truth - what I'm calling Durable Context.

Durable Context should be treated with the same care we currently (or really previously) gave to code. It was arguably always more important than the code (outcomes > implementation) but now it is certainly more important for building this shared source of truth to enable alignment at scale. So we need to continue thinking through our plans (as we have been) but also be much more strict about updating this context - ensuring we keep it up to date, it's accurate, there's one source of truth, it has the right shape and abstractions - much like the care we used to take with our code reviews. This is how we get the best of both worlds - the deep, slow thinking of humans and the mass automation of agents. For more: see Durable Context, Disposable Code.

Context Types

Moving onto more concrete implementations, I think we have a few context types we can compose together to approach this vision.

• Routers - How to find the appropriate information. Make search easy, give agents (and humans!) a way to get their bearings. For this we use AGENTS.md throughout the codebase as knowledge base index files for given areas.
  • Note: The PKM (Personal Knowledge Management) community uses a similar concept Maps of Content (MOCs) to gather, develop, and navigate related ideas.
• Skills - How to do a specific thing. These are the runbooks we discussed earlier.
• Durable Context - How a system should work. Why it exists, what it does, and how it does it along with supporting info.
• Change Context - How a system should change. Ephemeral Context that aligns a change and is merged into Durable Context as that change materializes.

Together this gives us a decent menu of context types to pull for a majority of our agent, human, and system alignment needs.

Context Hierarchies

I also think it's important to talk about Context Hierarchies. These are useful for constraining who is exposed to which bits of context / information and when. This helps you give the info someone needs at the time they need it while minimizing the noise from things they don't - a waste of AI tokens and human bandwidth.

We are natively familiar with many forms of context hierarchies - headers in a blog post to break things up, folders on a machine to organize files, the order and format information is presented in, etc. So I'm not going to dive into every form of Context Hierarchy because there's a ton of it and most people are already familiar with many kinds so I'll just leave you with an idea that it's important to consider this for agents just as it is for humans.

Organization Hierarchies

One Context Hierarchy I do want to expand on though is that of Organization Hierarchies. Orgs typically work best when they have a nice balance of top-down direction and bottom-up innovation. what that balance is depends on the co, its industry, and current economic conditions but generally I believe an org needs both to be effective.

• Top-down organization is good for sharing standards and best practices so everyone can benefit from these tools. Think standardized testing frameworks, dev servers, and deployment paradigms. You want enough top-down to make things efficient but not so much as to bog down your systems in processes and red tape.
• Bottom up is great for letting teams and individuals move fast and build the best workflows for them. Useful for unblocking teams, enabling people to work in the fashion that works best for them, and continually pushing forward the status quo. You want enough bottom up to let teams and individuals do their best work but not so much that you waste significant resources on duplicate or unaligned work, especially if a lot of it incurs ongoing maintenance burden.

So the idea is to provide flexibility at the lower levels and promote up to the org as things prove useful so everyone benefits. Everyone should get the org standards as a baseline setup and then lower levels can override higher levels in their specific usecases to make things work better for them.

We'll use an example of a team working on auth going forward to try and make some of these ideas more concrete.

At a high level the hierarchies I'm thinking of are:

• Organization - Best practices and standards that the organization sets out
  • Example Skills: How to run unit tests, how to spin up a dev server, how to deploy a service, how to review code as an agent (and how to pick up code standards as configured in the codebase)
  • Example Durable Context: What the product exists to do, shared engineering standards, deployment safety requirements (what's push-safe or not)
  • Example Change Context: Moving services to a shared deployment platform
• Team - Team-specific workflows that make sense for them, perhaps some overrides for some of the org workflows to be more effective for their usecases
  • Example Skills: Add a new OAuth provider, investigate a failed login using auth metrics and logs
  • Example Durable Context: How auth works (Architecture), what auth must guarantee (Requirements, like never linking accounts solely because emails match), what acceptance criteria and cases we want to ensure we verify (Verification, like rejecting an expired session)
  • Example Change Context: Adding Google OAuth Provider, improving auth latency with a target and a plan to measure it
• Individual - An individual's preferred working patterns.
  • Example Skills: Review a change with my preferred checklist, write BDD test cases, prepare a concise handoff for my next work session
  • Example Durable Context: For example in my AI Dotfiles I prefer functionalish logic, DDD modulithic code organization, and BDD testing.
  • Example Change Context: Updating a skill to be more effective, efficient

Though you could imagine this shape changes based on the org type and size to fit their actual structure.

Implementing Context Architectures

So I think there's several ways to do this at scale that work. I don't have a strong opinion on which to go with as they all work in theory under the proposed constraints and I'm still trialing various versions of them to try and figure out which works best in practice.

The core idea remains:

• Context Discovery - Provide the right context at the right time without adding undue noise at the wrong times
• Context Authority - Make clear what is the source of truth for each piece of guidance
• Context Change - Let teams experiment and promote useful practices into shared standards
• Context Maintenance - Keep context accurate as the systems and workflows change

A - All in one place

The first option is just having one big context structure.

repo/
├── AGENTS.md
├── .agents/skills/
│   ├── review-change/SKILL.md
│   ├── auth-testing/SKILL.md
│   └── billing-testing/SKILL.md
├── docs/
│   ├── organization/
│   │   └── engineering-standards.md
│   ├── auth/
│   │   ├── requirements.md
│   │   └── architecture.md
│   ├── billing/
│   │   ├── requirements.md
│   │   └── architecture.md
│   └── changes/
│       └── google-sign-in.md
└── packages/
    ├── auth/
    │   ├── AGENTS.md
    │   └── src/
    └── billing/
        ├── AGENTS.md
        └── src/

• Router - AGENTS.md scattered in codebase routing back to the appropriate context just like a web hyperlink. Located at meaningful locations like a package, folder, or important code path.
• Skills - Org and team/domain skills in repo (or shared plugins), individual skills in AI Dotfiles.
• Durable + Change Context - In a root docs/ folder suborganized by domain, team, or package depending on how your org organizes itself

Tradeoffs:

• Pros: Simple to understand
• Cons: Likely the context structure diverges from the system, context + system distance may make remembering to update harder

B - Distributed throughout codebase

This option moves context right next to where it's used for better locality of behavior.

repo/
├── AGENTS.md
├── .agents/skills/
│   └── review-change/SKILL.md
├── docs/
│   ├── engineering-standards.md
│   ├── system-architecture.md
│   └── changes/
│       └── cross-package-change.md
└── packages/
    ├── auth/
    │   ├── AGENTS.md
    │   ├── .agents/skills/
    │   │   └── auth-testing/SKILL.md
    │   ├── docs/
    │   │   ├── requirements.md
    │   │   ├── architecture.md
    │   │   └── changes/
    │   │       └── google-sign-in.md
    │   └── src/
    └── billing/
        ├── AGENTS.md
        ├── .agents/skills/
        │   └── billing-testing/SKILL.md
        ├── docs/
        │   ├── requirements.md
        │   └── architecture.md
        └── src/

• Router - AGENTS.md scattered in codebase routing back to the appropriate context just like a web hyperlink. Located at meaningful locations like a package, folder, or important code path.
• Skills - Org skills in repo, team/domain skills in shared plugins or the appropriate system folder, individual skills in AI Dotfiles.
• Durable Context - Located in docs/ folders in the system folder it relates to.
• Change Context - Cross-package changes live at the root docs/ folder; domain-specific changes live beside the affected domain, as with google-sign-in.md above.

Tradeoffs:

• Pros: Less noise by default as only relevant / discoverable in existing system folders, better locality so easier to remember to update docs as changes are made
• Cons: More distributed so more likely scattered context goes out of sync across context -> though if you get your system's boundaries right the conceptual and physical model of your systems should be pretty close

C - Hybrid

This option uses a bit of both, picking the best approach for the given scenario. It's likely this is the best option as we figure out where each wins out. I could imagine different domains / teams choosing different options for their repos and systems depending on what they're comfortable with and what makes the most sense.

Tradeoffs:

• Pros: More flexible per scenario
• Cons: Less standardized so potentially further risk of context drift as multiple guardrails / checks needed to cover the various paradigms

Best Practices for Context

Regardless of the context architecture you choose, there are a few best practices for this context we can leverage.

• Routers for available relevant context - Routers allow agents (and humans!) the ability to scan available context and only open those that it finds useful. This is usually done as a table / list of available context and a small description with a link. Plop these routers in appropriate places to help direct actors without filling up their context with useless information.
• Keep it concise and to the point - Agents love to overcommunicate which can waste a lot of tokens and cause humans to zone out. Agents are pretty smart these days and humans equipped with agents can parse a ton of files and links so it's okay (and preferred) not to repeat info very much.
• Single Source of truth - The best way to keep things aligned is to have a single source of truth that is the authority on that subject. This also makes it easier to keep this information up-to-date as you only need to update it in one place, not many.
• Keep it up-to-date - Context is only as good as it is accurate. Use skills and automated loops to parse the context and ensure they're up to date.
• Review the context - Context is arguably more important than code so we should likely spend more time reviewing and aligning on this than we do with code. If we can align on this Durable Context, then the code becomes disposable which allows us to get the benefits of human alignment with all the speed of agent swarms.
• Context + Systems should follow similar structures - This is the underlying idea behind DDD. Conceptually our systems should follow our mental model of the domain, not the other way around. The more we do this the easier it is to keep our Context Architectures and the Systems they describe aligned.

Next

So that's how I'm currently thinking about aligning humans and agents at scale. It's the same tried-and-true processes we've used in the past - PRDs, RFCs, tech specs, acceptance criteria, BDD (Behavior Driven Development / Design), DDD (Domain Driven Design), agile, information architectures, etc. We're just trying to translate it into a format that's more effective and efficient for humans and agents.

Quick shoutout to my Haminions Members for your continued support and making free posts like this possible. Haminions Members get access to my example project repo which includes monthly snapshots of my AI Dotfiles as well as dozens of example projects from the blog. If you liked this post, consider joining to support me making more.

If you liked this post you might also like:

• Durable Context, Disposable Code - Building Systems with Speed and Quality in the Agentic Era
• How I Actually Do Agentic Engineering As A Senior Software Engineer
• AI Dotfiles - How I Take My AI Workflows Across Projects And Machines