Top-Down vs Bottom-Up Specifications with Speckit: What Didn’t Work

[enricouniurb]

Recently, I experimented with Speckit to generate parts of a platform I’m building: UniContr, a full-stack system for managing university teaching contracts.

First attempt: a single global monolithic top-down specification

My initial idea was to write a specification describing the entire platform in one shot.

Build and evolve UniContr, a full-stack platform for the dematerialization and procedural management of university teaching contracts. The system must support SAML SSO authentication, role-based access control, end-to-end pre-contract workflows, integrations with U-GOV and Titulus, document generation, digital signatures, dashboards, and mobile-ready UI. The frontend should be an Angular SPA and the backend a Laravel API with JWT authorization, auditing, notifications, and document management.

The first generated code was basically unusable and required refining the specification repeatedly with ad-hoc corrections.

Second attempt: top-down modular specifications (somewhat resembling a bottom-up workflow)

The second strategy was to start from the architecture and grow the system incrementally.

Instead of one large specification, I split the platform into a sequence of smaller specifications with a technical constitution:

001-unicontr-platform-foundation

Production-ready full-stack platform for university teaching contract dematerialization, workflow management, system integrations, secure access, and role-based operations on desktop and mobile.

002-authentication
003-user-management
004-role-permissions
005-contract-management
006-contract-documents
007-audit-logging
008-notifications
009-search-filtering
010-dashboard-reporting

The result was slightly better and more controllable. However, the first generated code is still rarely usable as-is. Usually, it still requires refinement specifications with specific technical and graphical details.

Ultimately, AI code generation works best with well-structured prompts — I welcome any tips or experiences on using Speckit effectively in production.

[mnriem]

In case you haven't you can use clarify,checklistand analyze to help you there. Have you tried them?

[enricouniurb]

I tried using clarify, but for the large spec, the questions still felt too generic. I think applying a top-down modular approach would help improve the quality.

I would like to have a fully functional Laravel backend and Angular frontend application, including all the necessary architectural specifications.

[mnriem]

It depends quite a bit on the agent and the LLM model you are using on how large of a specification it can handle. Your top-down approach is how I would do it to anyway. Not only because of the agent and model restrictions, but also because I want to be able to review what was produced and the more features asked to implement the more you have to review.

[DuncanButler]

Sounds simple but with large projects like this, I tend to start with what I can get away with, an MVP if you like, but really a minimum almost just getting the app running in an environment, then each thing you want to add becomes a "feature" which can have its own spec etc, for example

1, build the basic homepage, including rollout to your environment etc,
2. Login feature, allow an existing user to log into the system, (for this we have to seed the DB with an existing user)
3. Add user feature allow an "admin" to add a user to the system

these are quite small features, but you get the idea, each stage builds on the previous, in a slice thought the eventual whole system. You could get your AI to figure out the best slices though the whole system given a basic list of required features, but a spec should always be a slice though the whole system, if you slice by say website, backend, database, then you will find getting things to join up correctly becomes an issue, and you don't get to see anything until the whole thing is completed.

[enricouniurb]

I use codex GPT-5.3-Codex.

I created a technical constitution with engineering rules aligned to my architectural and technological requirements.

Start with this specification
Build a production-ready, full-stack platform that generates university teaching contracts from structured assignment and personnel data, and manages the contract lifecycle end-to-end with secure access, role-based operations, and desktop + mobile parity for core workflows.

The generated output produced only a scaffolded backend structure (e.g., Laravel project layout) without full dependency installation, environment configuration and runtime readiness. The same behavior occurred on the frontend. The model generated architectural folders and partial code artifacts, but not a fully buildable, and executable system.

Should framework initialization be explicitly enforced in the constitution or plan, for example:

composer global require laravel/installer
laravel new example-app

Additionally, should I include links to the official Laravel and Angular documentation? If so, where should they be placed?

engineering-rules.md
constitution.md

[Nyrok]

Your experience matches a pattern I keep seeing: monolithic specs fail because the model can't tell which part is architecture vs which part is a UI constraint vs which part defines the output format. When everything is one blob, the model has to guess what matters most for any given generation step.

The modular approach (001-foundation, 002-authentication, etc.) works better because each spec has a narrower scope. But even within a single spec, the same problem exists at a smaller scale. Is this part a constraint? A goal? An example of expected output? If the model can't distinguish these, it hallucinates or ignores pieces.

What's helped in my work is making the type of each instruction explicit. Not just splitting by feature, but splitting by instruction type: role, constraints, output format, context, examples. Each type tells the model how to use that piece of information differently.

I built flompt around this idea. It decomposes prompts into 12 typed semantic blocks on a visual canvas and compiles to XML. For your case, imagine each spec having explicit blocks for "architectural constraints," "expected output structure," "tech stack rules," and "success criteria" instead of mixing them all into prose. The model would know exactly which rules to enforce during generation vs which parts describe the desired result.