Building a Solo AI Software Factory with Context Engineering

Key takeaways

1. ⭐ The three-question grid — the most reusable takeaway. all the tooling answers "What does the agent know?" (context, memory, code graph), "What can it do deterministically, without improvising?" (skills, procedures), "What stops it when it gets it wrong?" (hooks, architecture tests, quality gates). Instant audit grid: held up against any agentic setup, it reveals within three minutes which of the three is empty. The third one almost always is.
2. ⭐⭐ The guiding principle, worth memorizing verbatim. "What matters must be executable. An instruction is followed 'most of the time,' but it can be forgotten. A hook or a test is followed all the time." Stated even more sharply elsewhere regarding architecture tests: "it can't be bypassed, unlike a rule." → A rule is an intention, a test is a guarantee. This is the same thesis as the constraint ring in [[sfeir-code-review-anneau-contraintes-2026-07-30]] (published two days later) and the harness in [[osmani-agent-harness-engineering-2026-04-19]], but demonstrated on a real, solo setup, not stated as doctrine.
3. Explicitly against vibe coding. "Vibe coding as defined by Karpathy was experimentation and letting go. Here, I'm going to talk about context engineering." And the resulting responsibility clause: "Even if I don't write the code, I'm responsible for it and must keep control over it." Cf. [[karpathy-vibe-coding-agentic-engineering-software-3-0-2026-04-29]].
4. Software quality is not code quality. it includes intention (why, for whom) and Marty Cagan's four risks — Value, Usability, Feasibility, Viability — plus performance and reliability. This is what justifies layer 6 (product process) and explains why a purely technical software factory misses the point.
5. Layer 1 — context, and the move worth copying. three levels separated by their loading moment. Root CLAUDE.md (architecture, cross-cutting conventions, spec index) → permanent and short; .claude/rules/.md → conditional, activated by a paths: frontmatter (the Kotlin rule loads only when touching api//); .agents/.md → non-technical context (product positioning, personas, tone). ⭐ The rule, seen in full, is a routing table: it doesn't contain the procedures, it lists nine skills with the task that triggers each, to be opened only when needed. "If the AI isn't making a schema change, there's no point opening the db-migration skill." → Permanent context carries the index, not the content.*
6. ⭐ A long-term constraint encoded as context and as a test. — the text's best example: the author plans to open-source part of the code. The rule "code intended for open source must never depend on proprietary code" is written into the rules and verified by an architecture test (no file on the "open" side references the "proprietary" side; every production file belongs to one side or the other). "Writing a future constraint into the context avoids paying for a rewrite later." → A decision that doesn't exist yet can already be mechanically guaranteed.
7. The line that kills the magic prompt. "There's no point telling an AI to 'write quality code,' it's meaningless. You have to make your own constraints explicit." Paired with rare honesty: "A constraint is specific to a project and a person… Using feature flags isn't better or worse, it's just my preference."
8. Layer 2 — skills. "a procedure written once, replayed identically." Existence criterion: the third repetition. About thirty, across six families (backend, frontend, data, product cycle, operations/runbooks, writing). Two lessons: "multi-file procedure" skills are the most cost-effective ("adding a block to the content editor touches three rendering surfaces; without a skill, the agent systematically forgets one"), and "docs up to date" skills are critical on fast-moving code. ⚠️ Operational nuance: "This automatic loading can sometimes fail. In that case, you have to explicitly ask to use the skill." Cf. [[shihipar-claude-code-lessons-building-skills-2026-06-03]], [[agent-skills-anthropic-2025-10-16]], [[vincent-superpowers-agentic-skills-framework-github-2026-04-02]].
9. Sub-agents, in decline. reserved for tasks "that generate a lot of reading without much decision-making" (audits, broad exploration, doc drafting) — they "consume their own context and return a conclusion, not a file dump." But: "I use them less and less, recent agents do fairly targeted delegation themselves." Signal of evolution: a tooling practice partly made obsolete by the model.
10. ⭐ Layer 3 — GitNexus, the setup's most interesting tool. the repository is indexed as a graph (symbols, relations, execution flows), which yields impact(symbol) before modifying (blast radius, callers, risk level), detect_changes() before committing ("did I only touch what I meant to?"), searching for an execution flow rather than grepping a function name, and renaming via the call graph rather than find-and-replace. And the justification, which matters more than the tool itself: "The real issue isn't speed, it's detecting all the side effects of a change." → carried over into rule #4: "Measure impacts before and after the edit. We want to avoid the '1 bug fixed, 10 introduced' effect." Worth comparing to structured code-graph context versus vector RAG — the same family of argument as the Compare the Market result cited in [[sfeir-code-review-anneau-contraintes-2026-07-30]].
11. MCP, with a cost caveat. "I try to avoid MCPs that consume more context, but I still have a few" — JetBrains IDE (build, inspections, refactorings, indexed search), GitNexus, business services (payment, monitoring), database, browser. MCP is treated as a context expense to justify, not a given.
12. Layer 4 — hooks: the definition that matters. "scripts triggered by the agent's harness, not by the agent itself." Two production uses: before a shell call, reject the native build and redirect to the IDE build (faster, structured errors) while explaining the fallback; after a file write, run the formatter/linter. Other cited uses: blocking edits to generated files, requiring a test alongside any new module, forbidding a dangerous pattern.
13. ⭐ Pattern linting — the distinction worth keeping. ESLint for syntax, ast-grep for architecture decisions (example: forbidding any fetch call that bypasses the OpenAPI client), typecheck for typing. → An architecture decision can become a lint rule. This is the missing link between "we decided" and "it's enforced," and it costs a few lines.
14. Layer 5 — the gate. push to main → quality gate (lint → pattern lint → typecheck → tests) → build docker image → push to registry → deployment webhook. The structural point: the deployment job has a needs: on the quality job. "Nothing ships to production without passing the gate. That's essential as a general rule, even more so for automatically produced code." Five test stages: unit (heavily), integration with disposable containers ("real database and broker, no mocks"), architecture, front-end components, end-to-end on critical paths only. Cf. [[williams-adlc-3-tests-are-the-spec-2026-06-12]] and [[williams-adlc-2-two-human-gates-2026-06-12]].
15. Layer 6 — the product process, and the step everyone forgets. numbered specs (one per functional domain, indexed in the permanent context) framed by two skills — one for drafting the spec and its plan, one for closing it out by updating it with what was actually built. "Without it, specs become obsolete within six months," and as a final rule: "Spec documentation dies if its closing isn't part of the process." ⭐ Closing-out is the part of the documentation cycle that almost never exists elsewhere.
16. Anti-hallucination rule for specs. "If a spec is unclear or inconsistent with the existing system, the agent must ask, not guess." A single line of context addressing agentic development's costliest failure mode.
17. Staged delivery, and its rationale. the spec is designed to be delivered in stages protected by a feature flag, "it lets me do several small implementation sessions rather than one big session, which tends to degrade in quality once it fills up too much." → Here, product decomposition is dictated by long-context degradation, not project management. Useful distinction: feature flipping (Unleash — turning things on/off without redeploying: rollout, kill switch, maintenance) vs gating (configuration table + service — restricting by customer contract or plan). Two mechanisms, two needs, and a skill so agents don't conflate them.
18. Where to start (order given, and it's a good one). (1) the quality gate first, if it doesn't already exist; (2) a lightweight CLAUDE.md describing the essentials and the why; (3) rules added incrementally for important architecture patterns; (4) skills as soon as a procedure recurs; (5) CLI and MCP for the main tools. ⚠️ Security warning: "any skill, MCP, or code pulled in from outside must be scrutinized. These are dependencies that can be attack vectors." Worth comparing to the agentic attack surface described in [[clinton-anthropic-secure-ai-native-sdlc-2026-07-21]].
19. ⚠️ Lived limitations — the section that makes the page credible. 1. Rule obsolescence isn't measurable. "In mid-2025, 'write a test for every new service' made sense. Today it's noise and Claude does it naturally… I have no way to measure or know whether an old rule has become obsolete." → Accumulated context decays at the pace of the models, and nothing tracks that decay. This is the field's real methodological gap, and it's named here without a solution. 2. The rabbit hole. A boyscout.md rule ("always leave the code a bit better… flag improvements for me") produces "endless sessions" and cognitive overload. Envisioned fix: route these findings into a TODO list and move maintenance into a separate, partially automated workflow. → A good continuous-improvement instruction turns into a drift generator when the agent doesn't stop on its own. 3. No packaging. Skills and rules are copy-pasted from project to project, sometimes machine-dependent. Missing: a way to package for deployment and centralize maintenance. 4. Dependence on Claude, judged a "moderate risk" ("the whole ecosystem is moving upward"), with an interest in testing open-weight models — blocked by hardware. And the IDE has become a poor fit: "I still use IntelliJ but I no longer find it suited to our era. I haven't yet seen an interesting alternative."
20. ⭐⭐ The underlying admission, worth quoting verbatim. "The latest versions of Opus are increasingly autonomous… It's borderline unsettling, and more rigorous than 99% of humans. Let's be honest, I'm becoming less and less useful in the implementation phases, but I don't want to lose control of the code produced. I'm torn between the satisfaction of having an increasingly efficient software factory and the risk of losing the knowledge." → This is exactly the comprehension debt from [[osmani-cognitive-surrender-comprehension-debt-2026-05-05]], voiced from the inside by someone who built the most complete harness possible and observes that the harness doesn't solve that particular problem. The setup guarantees the code is correct; it doesn't guarantee the human still understands it. The text's open question: "I need to find a way to check the designs after the fact, to make the result my own."
21. ⚠️ Scope not to overstate. a solo setup, on personal products, with a single decision-maker. No multi-developer coordination, no peer review, no compliance or audit constraints — the "who validates" layer is occupied by a single person who is also the author of the rules. What carries over to a company setting: the three-question grid, the executable principle, spec closing, pattern linting. What doesn't carry over as-is: the total absence of any human gate other than oneself.
22. Meta / related. a practitioner's demonstration of [[osmani-agent-harness-engineering-2026-04-19]] and a direct cousin of [[sfeir-code-review-anneau-contraintes-2026-07-30]] (published 2 days later, same thesis: quality lives in the ring of constraints, not in the code); the same "software factory" vocabulary as [[wescale-usine-logicielle-augmentee-juge-strategique-2026-05-03]], but at the scale of one individual; stands in opposition to the vibe coding of [[karpathy-vibe-coding-agentic-engineering-software-3-0-2026-04-29]]; converges with [[klaassen-teach-ai-think-senior-engineer-every-2025-11-07]] on making constraints explicit; to be read alongside [[shihipar-claude-code-lessons-building-skills-2026-06-03]] on skills and [[williams-adlc-3-tests-are-the-spec-2026-06-12]] on tests.