AI-Assisted Development Overview

SaaS4Builders is designed from the ground up to be understood by AI coding agents. The project ships with configuration files, convention documents, and a structured execution system that make AI agents productive from the first prompt. This is not an afterthought — it is part of the architecture.

Whether you use Claude Code, Codex, Cursor, or another AI assistant, the same structured context that onboards the agent also onboards you. The conventions are the documentation. The documentation is the constraints.

Why AI-First DX Matters

AI coding agents produce inconsistent output when they lack project context. Without guidance, an agent will:

• Guess at file locations and naming conventions
• Use camelCase in API responses when your project uses snake_case
• Put business logic in controllers instead of domain Actions
• Create tests that don't follow your testing patterns
• Miss tenant isolation requirements entirely
• Invent API endpoints that don't exist in the route file
• Forget to scope database queries by tenant

The result is code that "works" in isolation but doesn't follow your architecture. You spend more time correcting the agent than you would writing the code yourself. And every correction you make is lost when the next session starts — the agent has no memory of your project conventions.

SaaS4Builders solves this by giving agents structured context — configuration files that describe the architecture, convention documents that define the rules, and an execution system that enforces the workflow. The agent's output matches what a senior developer familiar with the project would write.

The key insight: the same files that onboard AI agents also onboard human developers. There is no separate "AI documentation" layer. The convention files serve double duty — they constrain AI output AND document the project for you.

The Three Pillars

The AI-first DX system is built on three pillars: configuration, conventions, and execution.

Pillar 1 — Configuration (CLAUDE.md Files)

The project ships three CLAUDE.md files at strategic locations. These are the primary context files that Claude Code loads automatically:

When Claude Code opens the project, it loads the root file. When you work in backend/, it loads both root and backend. This layering means the agent always has the right level of context for the current work.

The configuration files are intentionally concise. The root file is ~150 lines — enough to navigate the project without overwhelming the agent's context window. Deep domain knowledge lives in skills, loaded on demand.

For the full configuration file breakdown, see CLAUDE.md Configuration.

Pillar 2 — Conventions (Structured Documents)

Six convention documents keep AI output consistent across the entire project:

These documents live in the docs/ and ai-context/ directories of the repository. Together, they form the project's living specification — over 3,900 lines of structured conventions that keep AI output consistent.

When an AI agent needs to create a new API endpoint, it reads the API Contracts document to learn the response format, the Backend Templates document for the code structure, and the Query Builder guide for filter/sort conventions. The output follows the same patterns as every other endpoint in the project.

For more on the architecture these conventions describe, see Architecture Overview and API Contracts.

Pillar 3 — Execution (Workplans and Work Units)

The workplan system provides a structured approach to feature development. Instead of giving an AI agent a vague instruction like "build a billing system," you give it a workplan — a Markdown document that specifies:

• A dependency graph showing the order of implementation
• Work Units (WUs) that break the feature into small, ordered tasks
• File lists specifying exactly what to create or modify
• Acceptance criteria that define when each WU is complete
• Verification commands to run after implementation

The entire SaaS4Builders codebase was built using this pattern. The billing system was implemented as a milestone with 12 Work Units, each specifying exact files, code patterns, and acceptance criteria. The teams feature, usage tracking, notifications — all followed the same structured approach.

A companion tracking file records progress as each Work Unit is completed, creating an audit trail of what was built, how it was verified, and what tests cover it.

Two skills support the workplan system:

• /create-workplan — An interactive skill that guides you through feature definition and produces a complete workplan with dependency graph and WU decomposition
• /implement-wu — A five-phase execution skill that reads the workplan, checks dependencies, presents a plan for approval, implements the code with tests, runs quality gates, and updates the tracking file

Together, they create a structured cycle: plan the feature, break it into WUs, execute each WU with AI assistance, track progress, and cascade to dependent WUs.

For the full workplan system, see Workplan Execution.

How the Pieces Fit Together

The three pillars work together through progressive disclosure — the agent loads only what it needs, when it needs it:

Developer prompt
     │
     ▼
CLAUDE.md (base context — always loaded)
     │
     ├── Need to work on billing?
     │   └── /docs/billing skill → loads billing conventions, rules, patterns
     │
     ├── Need to add an API endpoint?
     │   └── /new-api-endpoint skill → loads API contracts + code templates
     │
     ├── Need to implement a planned feature?
     │   └── /implement-wu skill → loads workplan + tracking file
     │
     └── Need to scaffold a full feature?
         └── /new-feature skill → loads backend + frontend checklists

The agent does not need the entire codebase context loaded at once. It needs the right context at the right time. The base CLAUDE.md files provide navigation and essential conventions. Skills provide deep domain expertise on demand. Workplans provide structured execution plans for complex features.

What This Means for You

For Human Developers

The convention files are your onboarding documentation. Read CLAUDE.md to understand the project structure. The Backend Templates show you how to write an Action or a Query. The API Contracts document tells you the response format for every endpoint. The Domain Glossary defines the business terminology.

You don't need separate "developer docs" and "AI docs" — they are the same files.

For AI-Assisted Workflows

Your coding agent produces convention-compliant code from the first prompt. There is no "train the AI" phase and no custom prompt engineering required. The guardrails are built into the project.

Agent Compatibility

The AI-first DX system is designed primarily for Claude Code, which natively supports CLAUDE.md files, skills, and the progressive disclosure model. However, the underlying patterns work with any AI coding agent.

Claude Code (Native Support)

Claude Code loads CLAUDE.md files automatically when entering a directory. Skills are invoked via /skill-name. The /implement-wu and /create-workplan skills provide structured execution workflows. This is the fully supported experience.

Other AI Agents

The convention documents (API contracts, templates, query builder guide) are plain Markdown files. Any AI agent can read them. To adapt the system for other agents:

• Context loading: Instruct the agent to read CLAUDE.md at the start of each session
• Skills: Copy the relevant skill's content into the agent's context when working on that domain
• Workplans: The workplan Markdown format works with any agent that can follow structured instructions
• Guardrails: Include the Critical Rules sections from relevant skills in the agent's system prompt

The convention files are the project's source of truth regardless of which agent you use. The patterns are agent-agnostic — the tooling around them (skills, automatic loading) is what makes Claude Code the most streamlined experience.

The Numbers

To give you a sense of the depth of AI context shipped with the boilerplate:

This is not generated boilerplate — every line was written, tested, and refined during the development of the SaaS4Builders features. The billing skill's "Common Mistakes" section exists because those exact mistakes were made and caught. The architecture rules exist because code was written that violated them.

What's Next

• CLAUDE.md Configuration — The three-tier configuration file structure and progressive disclosure model
• Skills System — On-demand domain expertise for AI agents, including the 15 shipped skills
• Workplan Execution — Structured AI-driven feature development with dependency management and progress tracking