← Index

How I Work

Structuring a Project for Internal Tools in 2026

TL;DR - Internal tools like admin systems, dashboards, and line-of-business apps are the bulk of real software, and they're where a well-structured AI-agentic workflow pays off the most. This is how I structure and ship a production internal tool in 2026, solo or in a small team. End-state first, spec-driven, local-first, AI-tested.

The context

Most software that actually runs a business isn't a flashy product. It's an internal tool. CRUD-heavy, multi-role, integration-heavy, used every day by people who depend on it. I've built several of them.

  • A security-clearance records system for a government ministry
  • An accommodation-management system for an institution
  • Internal admin dashboards

All of it solo or in small teams. 2-4 developers, 5 people on my biggest project. That's the scale I know, and honestly, that's the scale I believe in.

In 2026 the constraint on building these isn't typing speed. AI made execution nearly free. The constraint is structure. Without it, AI generates code fast and technical debt faster. With it, AI becomes a genuine force multiplier. So the whole game is how you set the project up.

How I structure the project

This is what a project looks like when I set it up.

tree
internal-tool/
├── CLAUDE.md              # the agent's context - conventions, commands, domain
├── .claude/
│   └── commands/          # custom slash commands + hooks
├── specs/
│   ├── 000-end-state.md   # what the finished system looks like
│   ├── 001-feature-a.md   # one concise spec per part
│   └── 002-feature-b.md
├── frontend/              # runs on localhost
├── backend/               # runs on localhost
└── tests/
    └── e2e/               # AI-written Playwright, guards every flow

MCP servers give the agent hands on top of this. Playwright drives the UI, Linear holds the work queue, Bitbucket takes the PRs.

  1. End-state and spec before code. I define what the finished system looks like, then decompose it into features and domains. Each part gets a concise spec before a line of code. The spec is where the understanding happens, and for an internal tool with real users and real data, understanding the domain is the whole job.
  2. DDD architecture. My default for almost every project I build right now. Bounded domains, clear layers, pure domain logic separated from the framework. It keeps a growing codebase understandable, and it maps perfectly onto agents - each domain is a scope an agent can own.
  3. Wire the AI environment. A CLAUDE.md gives the agent the project's context. Conventions, commands, the domain model. Every session starts smart.
  4. Build local-first. Every part of the app runs on localhost, and the agent has access to it. That means it verifies against the running system instead of writing hopeful code. It hits the real API, reads the real errors, sees real behavior. For a multi-part internal tool, the bugs live in how the parts connect, and only a running system surfaces them.
  5. Test with AI-written e2e. People use internal tools daily, so stability is non-negotiable. I write a few scenarios and let the agent expand them through the Playwright MCP. It finds the edge cases and weird role and permission flows I'd miss. The suite becomes a safety net that catches regressions before users do.
  6. One feature per session, agents in parallel. Build domain by domain against the spec. Specialized agents explore and plan in parallel. A well-scoped, spec-backed task is one an agent can actually complete.

The result

Production internal tools, shipped solo or with a small team. Stable, maintainable, with a commit history that shows the structure. On my accommodation system, the same discipline turned a codebase I'd initially rushed into one I could extend confidently, with AI-written tests guarding every flow.

The hard-won lesson

I learned this by doing it wrong first. I vibe-coded parts of a real internal tool, it felt done, and the technical debt came due. I rebuilt my whole methodology around structure, and the difference is night and day.

In 2026, the leverage isn't the AI model. It's the structure you put around it. A small team of developers with good structure and good domain knowledge can operate faster than a big corp. A few people with end-state-first specs, a local-first setup, AI-written tests, and scoped agent tasks ship internal tools at a level that used to require a whole department, without the debt hangover.

Stack - Claude Code, MCP (Playwright / Linear / Bitbucket), Playwright, DDD, local-first dev, spec-driven decomposition. Related case studies - the AI-agentic setup, spec-first development, AI-written e2e testing, local-first AI dev, and the accommodation lifecycle platform.

← Back to all