Body
This article describes practices relating to internal cloud development projects at the University of St. Thomas and is primarily intended for staff and student employees. It is not related to coursework or external business environments. With the rise of vibe-coding and AI-assisted development, it may be helpful to understand how the university approaches development projects.
Spec-driven development means writing formal specifications (requirements, design documents, and tasks) before writing code.
- Better AI Code Generation When using AI-assisted tools (like Kiro, St. Thomas's preferred agentic IDE), well-defined specs dramatically improve output quality. The AI has a clear, unambiguous target to work toward rather than inferring intent from vague prompts. This reduces hallucinated logic and misaligned implementations.
- Alignment Before Investment: Cloud resources (Lambda functions, API Gateway, DynamoDB tables, etc.) are easy to spin up but can be costly to redesign later. Specs surface architectural disagreements before infrastructure is provisioned, saving both time and cloud spend.
- Predictable, Repeatable Iteration: Specs act as a stable contract between iterations. When the AI agent (or a team member) refines or extends a feature, it can validate its output against the original spec which catches regressions early.
- Security and Compliance by Design: Cloud applications must meet IAM least-privilege, St. Thomas tagging policies, and monitoring requirements (CloudWatch, X-Ray). A spec that includes security requirements ensures these aren't afterthoughts — they're baked into the design from day one.
- Team Collaboration & Handoffs: Specs serve as shared truth across developers, stakeholders, and support teams. Since the St. Thomas ITS cloud philosophy emphasizes that "projects can be supported long after the original creator moves on," a spec ensures continuity without an individual's institutional knowledge.
- Testability: Specs with clear acceptance criteria map directly to unit, integration, and end-to-end tests. This supports automated pipelines (CodePipeline, CodeBuild) where tests must pass before deployment which is industry best practice.
- Microservice Boundary Clarity: Cloud-native apps are often composed of small, independent services. Specs define the interfaces between those services upfront, preventing integration surprises when components are combined.
Practical Tip for St. Thomas Developers
When working with the Kiro Agentic IDE (or any agentic IDE), use its planning and requirements features to define your idea before asking it to generate code. The more precise and well thought out your spec (inputs, outputs, edge cases, constraints), the more useful and governable the AI-generated implementation will be.
Steering Documents, Hooks, and Skills in Kiro
Before starting the spec workflow in Kiro, configure your project with steering documents, hooks, and skills that utilize St. Thomas's guardrails. This prevents the AI from recommending unapproved patterns and keeps every generated artifact compliant.
- Define approved AWS services and IaC tooling (SAM/CloudFormation)
- Specify deployment pipeline requirements (CodePipeline, CodeBuild, GitOps)
- Encode security baselines: IAM least-privilege, tagging, CloudWatch/X-Ray
- Reference St. Thomas starter templates and supported architectural patterns
Recommended Workflow for Spec-Driven Development
Use a structured, AI-assisted approach to building cloud applications grounded in St. Thomas AWS guardrails and designed to maximize the value of tools like Kiro. Kiro excels at the spec-driven workflow (requirements, design, tasks), but you get the most out of it when you prepare with iterative learning and planning first.
1. Learn
Understand the Problem Space
Before writing a single line of code or spec, use AI to build your own understanding. This phase is about you becoming informed not about generating deliverables.
Addy Osmani, a developer at Google, wrote about being deliberate about building expertise in the age of AI. The article goes over ways to inquire the AI about design choices it made so you can learn and not just accept it's output.
Explore the domain
Ask AI to explain the business problem, relevant concepts, and industry patterns. Build your vocabulary before you build your spec.
Make sure you don't just rely on AI, review documentation provided on the AWS documentation site as well as the St. Thomas Developer and Cloud Tools service page.
Research unfamiliar resources and patterns
If AI mentions a service or pattern you don't know — stop and learn it. Ask it to explain. Never accept a recommendation you can't defend.
Identify constraints early
Know the St. Thomas best practices for cloud development (AWS, serverless-first, approved patterns) before exploring options. This scopes your learning productively.
Build your mental model
You are the decision-maker. AI is a tutor. Arrive at the next phase with enough context to evaluate what the AI recommends.
2. State Goals and Iterate
Use a Multi-Role AI Evaluation
State your goal clearly, then instruct your AI assistant to evaluate it through multiple expert lenses simultaneously. Iterate. Answer its questions, challenge its assumptions (and have it challenge yours!), and research anything unfamiliar before moving on.
Assign these expert roles to your AI:
- Senior Project Manager
- Senior Cloud Architect and Engineer
- Senior Security Analyst
- Senior Software Engineer
- Senior Business Analyst
Take on the role of a senior level project manager, cloud architect and engineer, security analyst, software engineer, and business analyst. This is my goal {state your goal} this is how I think I want to approach it {add any constraints, guardrails, requirements, etc.} Challenge my assumptions, provide recommendations, and identify any gaps in my proposal.
Architectural Options
What are the viable approaches? What are the trade-offs in cost, complexity, scalability, and maintainability? (Be sure to right-size according to the size of your team and workload. A Docker image, load balancer, EC2, and unfamiliar languages may be too much if traffic is low and there is only one developer. Be sure to include team size and expected workload in your plan.)
Clarifying Questions
What does the AI need answered to give better recommendations? What assumptions is it making?
Don't assume or guess an answer. Ask someone who knows or look up the answer. If you are unsure of a question, ask the AI to explain. (Sometimes just ask: I don't know what you mean by X, please explain it to me as if I was new to the field)
Gaps & Risks
What's missing from your current thinking? What could go wrong? What edge cases haven't been considered?
Possible Solutions
For each gap or risk, what are the concrete options? Have the AI compare them from each role's perspective.
3. Plan
Decide and Finalize Direction
Consolidate what was learned in the iteration phase into a clear, agreed-upon direction. This is the last checkpoint before entering the formal spec workflow.
Lock decisions
Which architecture, services, and patterns are chosen? Document the "why" not just the "what."
Final questions
Are there any remaining ambiguities? Resolve them now — unanswered questions become bugs later.
(There may be more than one round of "final" questions!)
Scope boundary
Explicitly define what is in and out of scope. This directly shapes your requirements.
Output of this phase:
A plain-language summary of the chosen approach, key decisions made, open items resolved, and scope boundaries — ready to hand to the requirements phase.
4. Requirements
User Stories with Acceptance Criteria
Use the plan to generate structured requirements in the form of user stories. Kiro's spec workflow is purpose-built for this. Feed it your plan document and let it generate a first draft, then review and refine. Answer any open questions Kiro may have requested a decision or clarification on.
Kiro generates requirements documents with user stories and acceptance criteria:
User Story Format
As a [type of user],
I want [goal or action],
So that [business value or outcome].
Acceptance Criteria
Given [context],
When [action occurs],
Then [expected result].
This should not be a solo effort. Since these are text documents, they can be committed to the repository and shared among the human team for review and comment.
5. Design
Finalize How It Will Be Built
Translate requirements into a concrete technical design. Kiro generates design documents from your requirements. Your job is to validate that the design honors the decisions made in planning and stays within St. Thomas guidelines.
Review the document so that you know what will be built. Ask clarifying questions if necessary and request changes if you need to change course or something isn't exactly right.
Just like with the requirements, this should not be a solo effort. Share among your human team for review and comment.
6. Tasks
Build It
Kiro decomposes the design into discrete, actionable tasks and executes them as an agentic developer by writing code, creating SAM templates, scaffolding tests, and updating files. Because you prepared thoroughly, Kiro works within well-defined boundaries.
Traceable to spec
Every task links back to a requirement. Nothing gets built that wasn't specified.
Tests included
Acceptance criteria from requirements become the basis for unit and integration tests — not an afterthought.
Summary
Kiro excels at Requirements → Design → Tasks but the quality of that output is only as good as the preparation that precedes it. Phases 1–3 (Learn, Iterate, Plan) are where you do the thinking. Phases 4–6 are where Kiro does the heavy lifting guided by the clarity you created.
Learn More
Check out the related Knowledge Base articles to learn more about the benefits of using opinionated platforms and the DevOps and AI-assisted Engineering approach.