# Uncle Bob Martin: Refactoring For Agents

Status: deepened milieu note

## Source

- Date captured: 2026-06-19
- Source published date: 2026-06-19
- Source type: `X screenshot`
- Source title: `Refactoring for agents`
- Source URL: <https://x.com/unclebobmartin/status/2067935532580024741>
- Local source file:
  `external_material/archive/processed/https___x.com_unclebobmartin_status_2067935532580024741_s=46&t=DEtAIpP3vBwwioECC_VTAw.docx`

## People / Organizations

- Robert C. Martin / Uncle Bob
- Software engineering
- Coding agents

## Neutral Summary

The screenshot argues that refactoring means changing code structure for an
audience, and that the audience may now include agents. If humans and agents
consume code differently, then some code organization standards may shift. The
post specifically suggests that agents tolerate some differences from humans,
including somewhat larger functions and more useful comments.

## Theme Theory Relation

This source is directly relevant to the form of this project.

Theme Theory is being refactored for a new audience:

```text
messy corpus -> agent-legible idea surface
```

The project is not only making prose nicer for human readers. It is changing
the structure of the material so a future agent can ingest it, recover the
conceptual dependencies, and mediate the theory faithfully for a high-intent
person.

The tweet also validates a project design choice: agent-facing structure may
not be identical to publishable human essay structure. Comments, explicit
dependencies, repeated labels, concept sections, relation notes, inventories,
and recovery docs can all be more valuable to agents than they would be in
ordinary polished prose.

This does not mean the docs should become bloated. It means the standard is
different:

```text
not literary finish first
recoverable structure first
```

That is exactly the standard stated in
[What This Is](../../core/what-this-is.md).

## Deep Corpus Comparison

This source supports the artifact form more than the TT concept spine.

The corpus is being refactored for an unusual consuming audience:

```text
future humans + future agents working together.
```

That changes what counts as good structure. A polished essay might hide
dependencies for style. An agent-legible idea surface should expose them:

- names and aliases;
- source paths;
- concept edges;
- scope boundaries;
- promotion judgments;
- open questions;
- recovery docs.

The tweet also clarifies why MkDocs/repo browsing and plain Markdown matter.
The goal is not only human reading comfort. The goal is a durable structure
that agents can traverse without losing the intended relations.

This should influence project plumbing docs more than public core prose.

## Core Links

- [What This Is](../../core/what-this-is.md)
- [Linking And Relations](../../project/linking-and-relations.md)
- [Current State](../../review/current-state.md)

## Candidate Concepts / Edges

- refactoring -> changing structure for a consuming audience
- agents as audience -> agent-legible document standards
- comments -> explicit conceptual guidance
- larger functions/docs -> acceptable if dependencies remain recoverable
- idea surface -> codebase-like refactor of a corpus

## Promotion Judgment

- Promote to core? `maybe`
- Reason: useful external support for the agent-legible form of the project,
  especially if a future doc explains why the docs are structured this way.