# Investibook Project Philosophy *Software Engineering in the Agent Era* --- ## Preamble Investibook was built from day one as an experiment in agent-era software engineering. Not as a proof of concept, but as a production system with real users, real data, and real operational pressure. Along the way, we developed a set of principles — not borrowed from textbooks, but distilled from building, breaking, and rebuilding this system with AI agents as first-class contributors. This document captures those principles. It is meant to guide development decisions, inform new contributors (human and agent alike), and serve as a reference point when tradeoffs need to be made. We were heavily inspired by OpenAI's [Harness Engineering](https://openai.com/index/harness-engineering/) post, which articulated many ideas we had already been practicing. Where they built with Codex on an empty repo, we built with a mix of agents (OpenCode, Claude, Copilot) on a greenfield platform — and arrived at strikingly similar conclusions. This document captures both the shared principles and our own extensions. --- ## 1. Start Fresh, Migrate Knowledge > *We started with an empty git repository.* — OpenAI Harness Engineering Agent-era development should begin from a clean slate. Not because legacy code is bad, but because agents work best in environments designed for them from the ground up. Old codebases carry implicit assumptions — naming conventions that only make sense to the original author, configuration patterns that assume manual workflows, test structures that are human-navigable but agent-opaque. Starting fresh allows us to design the codebase, the repository structure, the documentation, and the development processes with agents in mind from day one. It lets us encode conventions explicitly in the repository — not buried in human memory or tribal knowledge. It lets us build scaffolding for agent legibility, verifiability, and autonomy without having to retrofit it onto an existing structure. **The principle**: Build new foundations for agents. Port knowledge, not code. --- ## 2. Blueprint-First Engineering > *The primary job of our engineering team became enabling the agents to do useful work.* — OpenAI Harness Engineering In traditional development, code is the primary artifact and documentation is the afterthought. In agent-era development, the relationship inverts. The most valuable human contribution is the blueprint — the design document, the architecture decision, the specification of intent. In Investibook, every major change begins with a dated design document in `docs/specs/`. The [product design](specs/2026-02-27-design.md) was written before the first component. The [codebase restructure](specs/2026-03-13-codebase-restructure.md) was planned as a phased spec with trade-off analysis before any file was moved. Bug fixes get postmortem documents in `docs/fixes/` explaining root cause and solution. This is not bureaucracy — it is leverage. A well-written spec lets an agent produce a correct implementation on the first pass. A vague ticket produces three rounds of review and rework. **The principle**: Write the design first. The code follows. Human engineers design; agents implement. --- ## 3. Repository as Cockpit > *We made repository knowledge the system of record.* — OpenAI Harness Engineering All project knowledge must live in the repository. Not in GitHub Issues. Not in Slack threads. Not in someone's head. The repository is the cockpit — the single place where the current state of the project, its history, its plans, and its philosophy are discoverable. Investibook's `docs/` directory is organized by lifecycle phase: ``` docs/ ├── specs/ — Design documents (dated, versioned) ├── guides/ — Configuration and integration procedures ├── research/ — Comparative analysis, evaluation, and option studies ├── plans/ — Roadmaps, backlogs, and implementation plans ├── fixes/ — Post-deployment corrections and lessons learned ├── sops/ — Operational templates and incident process documents ├── philosophy/ — Philosophy documents (this document lives here) ├── troubleshooting.md — Operational debugging reference └── SUMMARY.md — Canonical table of contents ``` `AGENTS.md` at the repository root serves as the entry point — a table of contents that points agents to deeper sources of truth. It is not an exhaustive instruction manual; it is a map. Even for a mature project that starts without this structure, a few iterations of agent-driven development will naturally produce a document-based cockpit. Plans become markdown files. Decisions become specs. Bugs become fix documents. The repository converges toward being its own knowledge base. **The principle**: If it's not in the repo, it doesn't exist — for agents or for future humans. The repository is the cockpit of the project. --- ## 4. Agent Legibility Is the Primary Design Constraint > *From the agent's point of view, anything it can't access in-context while running effectively doesn't exist.* — OpenAI Harness Engineering Code should tell everything. Project structure should be agent-readable, agent-usable, and agent-testable. When making a design decision, the first question is: "Can an agent understand this and work with it?" This means favoring explicitness over cleverness. Prefer typed contracts over implicit conventions. Prefer flat, named structures over deeply nested hierarchies. Prefer simple file-based interfaces over in-memory state that only a running process can observe. Prefer well-bounded modules with clear entry points over sprawling files that require reading thousands of lines to understand. Technologies often described as "boring" tend to be easier for agents to model: they have stable APIs, broad training representation, and predictable behavior. In some cases it's better to reimplement a small subset of functionality in-repo — tightly integrated with the codebase's own conventions — than to depend on an opaque upstream package whose behavior the agent can only guess at. The corollary: agents are the first-class developers; humans are the first-class designers and alignment-checkers. We optimize the codebase for agent productivity, and we optimize the review process for human judgment. **The principle**: Design for agent legibility first. If an agent can't navigate it, reason about it, and modify it — refactor until it can. --- ## 5. Architecture as Conflict Prevention > *Enforcing invariants, not micromanaging implementations.* — OpenAI Harness Engineering In agent-era development, code conflicts are more expensive than code errors. An error can be detected by CI and fixed in a follow-up PR within minutes. A merge conflict requires ambiguous judgment calls, and agents handle ambiguity poorly. This reframes architecture: the primary goal of code structure is to minimize the probability that two concurrent changes touch the same lines. The pattern is: one concern, one location. Each domain of work should have a clearly designated home — route handlers in one place, data access in another, UI components in isolated folders. When the location for a change is unambiguous, parallel agents can work without stepping on each other. Strict boundaries with local autonomy. The architecture defines where things go; agents decide how things work within those boundaries. Constraints are enforced structurally — through linters, directory conventions, and module boundaries — not through code review gatekeeping. **The principle**: Design code structure to minimize merge conflicts. In the agent era, structural conflicts cost more than bugs — bugs can be fixed in minutes, conflicts require human arbitration. --- ## 6. Fast Merge, Cheap Fix > *Corrections are cheap, and waiting is expensive.* — OpenAI Harness Engineering The conventional PR workflow — human review, approval gates, clean commit history — was designed for a world where code changes are expensive to produce and expensive to fix. In the agent era, neither is true. Our merge philosophy: - **Development branches merge freely.** The cost of a broken dev branch is a follow-up PR. The cost of blocking a dev branch is stalled momentum across all parallel work. - **Commit-only workflow.** We don't squash-and-rebase to keep history pristine. We commit forward. If something is wrong, we revert with a new PR. Traceability and fast merging matter more than a clean `git log`. - **Human review is for alignment, not correctness.** Humans review to check whether the change matches intent and design. Correctness is verified by tests and CI. Having a human "hold" a PR to manually verify correctness is no longer the best use of the scarcest resource. - **Revert over block.** If a merged change causes problems, revert it. Don't prevent merging to avoid the possibility of reverting. The revert-and-fix loop is faster than the review-and-block loop. This requires courage. Teams accustomed to gatekeeping must learn to trust the system — CI, type checking, tests, and the low cost of agent-generated fixes. **The principle**: Merge fast, fix forward. A reverted PR is cheaper than a blocked pipeline. Optimize for throughput, not for the appearance of control. --- ## 7. Closing the Loop: Agent-Verifiable Changes > *We made the app bootable per git worktree, so Codex could launch and drive one instance per change.* — OpenAI Harness Engineering The ideal development loop is not "agent writes code → human reviews code." It is "agent writes code → agent verifies the result → human reviews the outcome." Every PR should be self-verifying: the agent runs the application, exercises the change, and reports the result. Human engineers evaluate outcomes — screenshots, rendered UI, metrics, behavior — not diffs. This shifts the human role from correctness gatekeeper to intent validator. To make this possible, applications must be designed for programmatic observability from the start. State should be readable via API, not locked inside a running process. Interfaces should be drivable from non-browser clients. Outputs — visual or data — should be capturable and comparable. When the application is legible to the agent as a running system, not just as source code, the feedback loop closes. **The principle**: Every PR should be runnable and verifiable by an agent. Humans review results, not code. Push toward closed-loop verification where the agent demonstrates that its change works. --- ## 8. Extend the Agent's Reach > *Given a single prompt, the agent can now validate, reproduce, fix, verify, and merge.* — OpenAI Harness Engineering The development lifecycle has distinct phases: ``` Idea → Design Doc → UI/UX Mockup → Implementation → Verification → Delivery → Production ``` Each phase that requires human intervention is a bottleneck. The goal is to progressively extend the agent's coverage across this pipeline — not to eliminate humans, but to convert human concerns into development tasks that agents can execute. When a human has a concern, the response should not be to hand it to a human engineer to investigate for days. The response is to make that concern measurable and expressible as a task — with clear input, clear acceptance criteria, and a clear output — and let the agent handle it. Human judgment is spent on defining what good looks like, not on doing the work. This requires investing in the scaffolding that gives agents access to each phase: design templates that produce consistently structured specs, UI/UX mockup flows that agents can render and compare, evaluation harnesses that translate acceptance criteria into executable checks. The more phases are scaffolded, the more of the pipeline is agent-coverable. **The principle**: Convert human concerns into agent-executable tasks. Extend the agent's reach across more phases of the development lifecycle. Every phase an agent can cover is a phase that scales. --- ## 9. Entropy Management and Code Garbage Collection > *Technical debt is like a high-interest loan.* — OpenAI Harness Engineering Agents replicate patterns they find in the codebase — including bad ones. Without active maintenance, agent-generated code drifts toward entropy: duplicated utilities, inconsistent naming, deprecated patterns that persist because nothing removes them. The approach is twofold: encode conventions so agents inherit them automatically, and run periodic cleanup that catches drift before it compounds. Coding standards, naming conventions, and structural rules belong in the repository's agent-instruction files — not in shared human memory that new contributors (or new agent sessions) must independently rediscover. Legacy code marked for removal should be explicitly annotated, not quietly tolerated until someone trips over it. At the right moment in a project's maturity — when the product has stabilized enough to reason about structure, but before entropy has compounded too far — a deeper architectural restructuring is worth the investment. This is not just cleanup: it is a deliberate re-alignment of the codebase with what the project has become, rather than what it was when first built. Done well, a restructuring sprint pays dividends that compound: agents produce better-located code, onboarding new contributors becomes faster, and the mental model of the codebase stays coherent as the project grows. The key is timing it as a planned, documented effort — not as an emergency response to dysfunction. What we haven't yet fully realized: automated code GC — background tasks that scan for dead code, unused imports, and stale patterns, then open targeted cleanup PRs. This is the next frontier: human taste encoded once, enforced continuously by the system itself. **The principle**: Agent-generated codebases need active garbage collection. Restructure intentionally, enforce conventions mechanically, and treat technical debt as a continuous cost — not a deferred one. --- ## 10. Context-Gated Delivery This is our own addition to the agent-era engineering playbook — a principle we developed from the realities of multi-person collaboration in a fast-moving project. ### The Problem In traditional development, features are delivered when they are "done" — implementation complete, tests passing, review approved. But in practice, the right time to deliver a feature depends on much more than its implementation status: - **Collaboration dynamics**: What is the team focused on right now? A feature that works as a demo may carry a high cost to ship properly — hardening edge cases, coordinating dependencies, updating documentation. Is this the right moment to absorb that cost? - **Stakeholder concerns**: What are stakeholders currently worried about? Does this feature address a current priority or a future one? - **External technical momentum**: What is the industry doing? Is there a technology shift that makes this feature more or less relevant? - **User readiness**: Can users absorb this change? Are they asking for it, or will it confuse them? ### The Principle **Features can be developed ahead of time, but delivery should be selected by fit, not merely by readiness.** A feature is *ready* when implementation is done. A change is *shippable* when the organization, stakeholder context, technical environment, and user state can absorb it at the lowest cost. ### How It Works ``` Development ←→ Asynchronous, continuous, unconstrained │ ▼ Delivery ←→ Context-gated: collaboration dynamics, stakeholder concerns, external momentum, user readiness ``` - **Build broadly, ship selectively.** Development runs ahead of delivery. Features are built when the agent (or engineer) has momentum, regardless of whether the team is ready to absorb the change. - **Context gates delivery, not development.** The "organizational fit" of a change determines when it ships — not when the PR is green. A perfectly implemented feature may sit in a branch for a week because the team is focused on a critical bug fix, and merging it now would split attention. - **Lowest-cost delivery wins.** When choosing what to ship next, ask: "Which change can be absorbed at the lowest cost and creates the strongest next-step leverage?" This is not about shipping the biggest or most complete feature. It's about shipping the change that fits. - **Async development is sacred.** The context gate only applies to delivery (merging to main, deploying to production, announcing to users). Development itself — writing code, building prototypes, exploring approaches — should never be blocked by organizational rhythm. ### In Practice Once a product is live, user feedback becomes a voting mechanism on the reserve backlog. Many requests that arrive after launch are already covered — fully or partially — by draft PRs or staged features that haven't shipped yet. The feedback doesn't create new work; it reprioritizes existing work. Features tend to sit in reserve for one of four reasons: 1. **Lacking validated user experience**: The implementation is ready, but hasn't been tested against real users in a real context. Shipping prematurely risks baking in the wrong UX before we understand how users actually behave. 2. **Organizational direction is unresolved**: There is internal disagreement about the product's next evolution. Shipping a feature that assumes a particular direction can foreclose better options. It's better to wait for alignment than to ship and create migration cost. 3. **Current shipping cost is high, but will decrease**: Some features are expensive to ship today — they require documentation, coordination, or infrastructure that isn't ready. The same feature may be much cheaper to ship in a future sprint when supporting work is already in place. 4. **Priority ordering**: Other changes deliver more leverage right now. The feature is good, but not the best use of the current delivery window. The reserve backlog is not failure — it is optionality. Features built ahead of time and held in reserve are ready to ship the moment the context becomes favorable. User feedback, leadership signals, and external momentum all serve as inputs to that decision. **The principle**: Let development run ahead. Let context decide delivery. Build broadly, ship selectively. --- ## Summary of Principles | # | Principle | One-liner | |---|-----------|-----------| | 1 | Start Fresh, Migrate Knowledge | Build new for agents; port knowledge, not code | | 2 | Blueprint-First Engineering | Design docs before code; specs are the highest-leverage artifact | | 3 | Repository as Cockpit | All project knowledge lives in the repo — it's the single source of truth | | 4 | Agent Legibility First | Design code for agents to read, navigate, and modify | | 5 | Architecture as Conflict Prevention | Structure code to minimize merge conflicts, not just to organize logic | | 6 | Fast Merge, Cheap Fix | Merge fast, fix forward; revert over block | | 7 | Agent-Verifiable Changes | Every PR should be runnable and verifiable by an agent | | 8 | Extend the Agent's Reach | Convert human concerns into agent-executable tasks | | 9 | Entropy Management | Agent codebases need active garbage collection | | 10 | Context-Gated Delivery | Build broadly, ship selectively; let context decide delivery | --- ## What We're Still Learning We don't have answers to everything. Open questions we're actively exploring: - **How does architectural coherence evolve** when agents contribute the majority of code over months and years? - **Where does human judgment add the most leverage** — and how do we encode that judgment so it compounds instead of being spent once? - **How do we automate code garbage collection** effectively — scanning for drift, dead code, and pattern decay without generating false-positive cleanup PRs? - **How do we make visual verification work** — having agents render, screenshot, and compare UI changes as part of the PR loop? - **How does Context-Gated Delivery scale** to larger teams — is it a team-level discipline, or does it need tooling support? What's clear: building software still demands discipline. But in the agent era, the discipline shows up in the scaffolding — the documents, the architecture boundaries, the feedback loops, the delivery gates — rather than in the code itself. The code is the easy part now. The hard part is designing the environment where agents can produce correct, maintainable, coherent software at scale. That's what this philosophy is about. --- *This document is a living artifact. It should be updated as our practices evolve and our understanding deepens.*