Background
Alex had been building with Cursor for six months when he adopted ShipAI. He'd found that AI-assisted development was powerful but unpredictable — Cursor would generate code that worked but didn't fit the existing codebase style, used different patterns than established ones, or required significant manual cleanup to be mergeable. The problem wasn't the AI model; it was the lack of codebase context.
The challenge
Alex needed an AI development workflow where Cursor-generated code would be consistently coherent with the existing codebase — using the same folder conventions, following the same API route patterns, using the established data fetching approaches, and applying the correct TypeScript types from the existing type definitions. Without that consistency, AI-assisted development created as much review work as it saved.
How they built it
AGENTS.md as the codebase specification
ShipAI includes an AGENTS.md file that documents the codebase architecture, naming conventions, data flow patterns, service boundaries, and implementation examples for AI coding agents. When Alex opens a feature prompt in Cursor, the AGENTS.md is included in the context. Cursor generates code that follows the documented patterns rather than inventing its own.
10+ skill packages for specific domains
Beyond AGENTS.md, ShipAI includes over 10 agent skill packages that give Cursor specific implementation guidance for different areas: auth flows, billing integration, AI handler adaptation, SEO page generation, and more. When Alex asks Cursor to add a new billing tier or create a programmatic SEO page, the relevant skill package provides precise implementation guidance.
Type-safe context from the start
Cursor's code generation is significantly better when it can see the TypeScript types for the data it's working with. ShipAI's comprehensive type definitions — for database schema, API responses, user sessions, billing plans — give Cursor accurate types to reference. Generated code uses the correct types rather than guessing or using `any`.
Mergeable AI output, not draft output
Alex's workflow is to write a detailed feature prompt, review the generated code, and merge with minimal changes. Before ShipAI, 60–70% of Cursor-generated code required structural changes before it was mergeable. After ShipAI, that number dropped to under 20%. The remaining changes are usually domain-specific logic, not structural corrections.
Outcomes
3x feature output
Alex shipped roughly 3x as many features per week after adopting ShipAI's AI-assisted workflow, measured by completed PRs.
AI-generated code cleanup from 65% to 18%
The percentage of Cursor-generated code requiring structural changes before merging dropped from approximately 65% to 18%.
AGENTS.md context used in every session
Alex includes AGENTS.md in every Cursor session by default. He describes it as 'the difference between a contractor who's read the codebase and one who hasn't.'
Zero architecture regressions from AI code
In four months of AI-assisted development with ShipAI, no AI-generated code has introduced architectural regressions or required a structural revert.
In their own words
The AGENTS.md is the thing most people underestimate. It looks like documentation, but it's actually a specification for how Cursor should think about your codebase. When Cursor has it, the code it generates is structurally correct the first time. I'm not cleaning up AI output — I'm reviewing product logic. That's a completely different kind of work.
“Cursor knows the entire codebase from day one because of the AGENTS.md spec. I describe what I want in a feature prompt and Cursor generates coherent code that fits the existing patterns. I'm building faster than I ever have, and the output doesn't need major cleanup. That's rare with AI-assisted development.”
— Alex Oduya
Frequently asked questions
What does AGENTS.md include?
AGENTS.md documents the codebase architecture, key file locations, naming conventions, data flow patterns, service boundaries, and implementation examples for common tasks. It's designed to give AI coding agents (Cursor, GitHub Copilot, Claude) the context needed to generate coherent code without needing to explore the codebase manually.
Does AGENTS.md need to be maintained as the codebase evolves?
Yes, but it's lightweight. Alex updates AGENTS.md when he adds new service boundaries or establishes new patterns. He treats it as a contract with the AI — keeping it accurate takes about 10 minutes per week and pays back significantly in generation quality.
Does this work with tools other than Cursor?
Yes. The AGENTS.md spec and skill packages are designed to work with any context-window-based coding assistant — GitHub Copilot Chat, Claude, and others. Alex primarily uses Cursor but has tested with Claude for complex refactoring tasks.