Skip to content
kevinferron.com

C3 · Software factories: an old word for a new line · Interactive, in your browser

Encoding what makes your software yours

Where should a lesson live so the next run starts with it, and which of those places actually enforce it?

Jacob says each factory is its own. Anthropic’s docs say which places only advise and which enforce. The figure places six invented lessons and counts what is enforced.

Try an arrangement

  • L1Start the dev server on a free port(fact)

    Fits

  • L2How to add a chapter to a series(procedure)

    Fits

  • L3Never push to main without the owner’s go-ahead(irreversible)

    Fits

  • L4Never type a price into a page(testable)

    Fits

  • L5Write in the site’s voice(judgement)

    Fits

  • L6A file the browser loads must not import internal notes(testable)

    Fits

Enforced
0
Always loaded
6
Fit
6
Nothing to test, or needs a judge
0

What the docs say each place does

Instructions file
Enforced: no
Acts: Every session
In context: Always loaded
Skill
Enforced: no
Acts: When it is used
In context: Its description always, its body on use
Subagent
Enforced: tools only
Acts: When that agent runs
In context: Its own context window
Hook
Enforced: yes
Acts: Before a tool call
In context: Only its message, when it fires
Check in the gate
Enforced: yes
Acts: At the gate
In context: None

Invented: the six lessons are of the kinds this site has. The places and what they do come from Anthropic’s docs. Which lesson fits where is my reading. A fact or a procedure in a hook or a check has nothing to test, and a judgement there needs a model to judge it, which the hooks guide gives to prompt-based hooks.

Jacob says each team’s factory is its own, set by the software it makes and the team that runs it. When a failure gets through, don’t blame the model, he says. Change the factory so that whole class of error is caught more often.

Jacob also says to write the architecture down as a skill, so generated code can be reviewed against it. But skills alone aren’t enough, he says. They belong inside a system with inputs, outputs and measurement.

Start small, build the basic thing, then encode more of what makes your software unique. That’s how Jacob’s post of 5 November 2026 puts it.

Greenfield’s 2004 article points the same way. It says to let developers encapsulate what they know as reusable assets, moving from documentation to automation.

Where a lesson lives decides whether the next run follows it or only reads it. The lesson is the asset.

Anthropic’s docs say instruction files load every session, and that “Claude treats them as context, not enforced configuration.” The docs aim for under 200 lines per file. Longer ones use more context and reduce adherence.

The docs say to make a skill when part of an instruction file has grown into a procedure. Its description is always in context. Its body loads only when it’s used.

A subagent runs in its own context window, with its own prompt. Its tools field, the docs say, is an allowlist.

A hook runs at a fixed point and gives deterministic control. The docs give two cases. A PreToolUse hook that exits with code 2 blocks the tool call, and a task-completed hook can refuse to mark a task done.

The authors of DORA’s 2025 survey name automated testing among the controls that keep a rise in change volume from turning into instability. A check in the gate refuses a change after the fact.

Swamp Club’s software-factory extension goes a step further and makes the lifecycle itself data. It has gates, one of them human approval, and a cycle limit of five by default. Past that, the run parks until a person grants an override.

On this site a rule that matters is written twice: as guidance in AGENTS.md, and as a check that fails when it’s broken (a price in a page, a browser file importing internal notes, a draft flag). A hook asks before a push to main. Skills hold the procedures.

The docs aim for under 200 lines per file. This site’s AGENTS.md is 463 lines long.

How instruction files should be organised is a Harness question, and Harness covers it.

Limits and counter-evidence

The figure takes every place from the docs of one vendor. Other tools differ.

The docs say not to count on a stalled hook, and to use the permission system for a hard allow or deny. A hook isn’t a perfect gate.

Jacob is a founder, and his claims are about his own product.

Longer instruction files use more context and reduce adherence, the docs say, and a skill’s description is always in context. Encoding has a context cost.

Sources

  1. Syntax episode 1049, 2026 (founder interview, podcast) WTF is a Software Factory? (Adam Jacob with Wes Bos and Scott Tolinski). Show page and transcript, 21 October 2026, timestamps from the transcript; read 2026-11-05.

    No two factories are the same; black-box acceptance tests first; doubts about how much unit tests add now; the architecture written down as a skill; changing the factory when a failure gets through; skills inside a system with inputs, outputs and measurement.

    • 10:44 to 13:48 and 43:56 to 46:17
    • 41:26 to 42:46 and 46:41 to 47:55
    • The interview

  2. Jacob, 2026 (founder’s opinion) Adaptive Building Blocks. Blog post, 9 April 2026; read 2026-11-05.

    His factory has its own needs, set by the software it should produce, and everything else should adapt to them; Swamp’s development moved off GitHub as more of the lifecycle happens inside the agent.

    • His factory has its own needs
    • The post

  3. Jacob on X, 2026 (founder’s opinion) Post on X, 5 November 2026. Post on X, read in Claude in Chrome (x.com refuses plain fetches); read 2026-11-05.

    Start small, build the basic thing, then encode more of what makes your software unique; small primitives over big answers.

    • The post

  4. Greenfield, Microsoft, 2004 (vendor) The Case for Software Factories. Microsoft’s own article in The Architecture Journal, July 2004, in Microsoft’s archive; read 2026-11-05.

    A Software Factory as a development environment configured for one type of application; economies of scope, not scale; development never purely mechanical; letting developers encapsulate what they know as reusable assets.

    • What Will Industrialization Look Like?

  5. Claude Code docs, memory (vendor docs) How Claude remembers your project. Anthropic’s documentation; read 2026-11-05.

    Instruction files load every session and are context, not enforced configuration; aim for under 200 lines; a PreToolUse hook blocks an action regardless of what the model decides.

    • Instruction files and their size
    • Size: under 200 lines per file
    • The docs
    • Longer files use more context and reduce adherence
    • Instruction files are context, not enforced configuration

  6. Claude Code docs, skills (vendor docs) Extend Claude with skills. Anthropic’s documentation; read 2026-11-05.

    A skill’s description is in context in a regular session and its body loads only when it is used; make one when part of an instruction file has grown into a procedure.

    • Descriptions, bodies and when to make a skill
    • Descriptions are always in context
    • The description is in context; the body loads when invoked

  7. Claude Code docs, subagents (vendor docs) Subagents. Anthropic’s documentation; read 2026-11-05.

    Each subagent runs in its own context window with its own system prompt, and its tools field is an allowlist.

    • Context, prompt and tools
    • Its own context and prompt; tools is an allowlist

  8. Claude Code docs, hooks guide (vendor docs) Automate actions with hooks. Anthropic’s documentation; read 2026-11-05.

    Hooks run at fixed points and give deterministic control, so certain actions always happen instead of relying on the model to choose them; judgement calls go to prompt-based hooks.

    • Deterministic control
    • Judgement calls go to prompt-based hooks

  9. Claude Code docs, hooks reference (vendor docs) Hooks reference. Anthropic’s documentation; read 2026-11-05.

    Exit code 2 on a PreToolUse hook blocks the tool call; a task-completed hook can refuse to mark a task done; do not count on a stalled hook as a gate, and use the permission system for a hard allow or deny.

    • Exit code 2 and the task-completed hook
    • The reference
    • Do not count on a stalled hook as a gate
    • Exit code 2 on a PreToolUse hook blocks the call

  10. DORA 2025, Google Cloud (vendor-run survey) Announcing the 2025 DORA Report: State of AI-Assisted Software Development. Google Cloud blog, 23 September 2025; the report PDF was not read; read 2026-11-05.

    A survey of nearly 5,000 technology professionals: AI adoption goes with higher delivery throughput and with lower delivery stability; the authors’ explanation is change volume outrunning controls such as automated testing, version control and feedback loops.

    • The explanation of instability

  11. Swamp Club software-factory extension (vendor docs) @swamp/software-factory. The vendor’s extension page, version 2026.10.23.1; read 2026-11-05.

    A model-driven state machine for guiding agents through a development lifecycle in which stages, transitions, gates and skills are data; a human-approval gate; a cycle limit, five by default, past which the run parks until a person grants an override.

    • Gates, human approval and the cycle limit

Each fact is paraphrased from the page named, read on the date shown. A company’s own page is marked as the vendor’s claim, an essay or a post as opinion, and the survey as vendor-run. None of it is a measurement of this site. Where a sentence is my own reading, it is marked “My view”.