Agentic Coding: Requirements - THE LGTM

Agentic Coding: Requirements

The gap between "what we want" and "what we get" from AI agents is a requirements problem. Here's how to write specs that agents can execute — and humans can validate.

Last Updated: April 5, 2026

The Requirements Challenge

Vague requirements → agent makes assumptions → wrong implementation → rework.

Example of vague: "Add user authentication"

What the agent might do:

• Basic email/password login
• Passwords stored plaintext (oops)
• No session management
• No password reset
• No rate limiting

The fix: Structured, explicit requirements.

The SPEC Format

A simple template for agent-friendly requirements:

## Feature: User Authentication

### Context
Users need secure access to the platform. Compliance requires audit logging.

### Goals
- Secure authentication (OWASP compliant)
- Self-service password recovery
- Session management
- Rate limiting for brute force protection

### Non-Goals
- Social login (Phase 2)
- MFA (Phase 2)
- SSO integration

### Acceptance Criteria
- [ ] User can register with email/password
- [ ] Passwords hashed with bcrypt (cost factor 12)
- [ ] Login creates session valid for 24h
- [ ] Failed logins rate-limited (5 attempts / 15 min)
- [ ] Password reset via email link (expires 1h)
- [ ] All auth events logged (user, timestamp, IP, result)

### Technical Notes
- Use existing UserRepository
- Sessions stored in Redis
- Email service already configured
- Follow patterns in src/features/auth/

### Out of Scope
- Admin dashboard
- User profile management
- Account deletion

Requirements as Prompts

The Structure

Effective agent prompts for requirements include:

1. Context: Why this matters, background
2. Goals: What success looks like
3. Constraints: Technical limits, must-use patterns
4. Acceptance: Specific, verifiable criteria
5. References: Similar features, existing code
6. Boundaries: What's NOT included

Example Prompt

Implement password reset feature per SPEC.md:

Requirements:
- Generate secure random token (32 bytes, URL-safe)
- Store token hash (not plaintext) in DB with expiry
- Send email with reset link (use EmailService)
- Link expires in 1 hour
- Validate token on reset page load
- Allow new password submission if valid
- Invalidate token after use
- Rate limit: 3 reset requests per hour per email

Constraints:
- Use existing UserRepository for DB operations
- Follow patterns in src/features/auth/
- Use zod for validation
- Log all reset attempts (success and failure)

Reference: See forgot-password-flow.md for sequence diagram

Test cases:
1. Valid email → receives reset email
2. Invalid email → generic success (no enumeration)
3. Expired token → error message
4. Used token → error message
5. Weak password → validation error

Spec-Driven Development (Kiro Pattern)

Kiro formalizes this into a workflow:

Phase 1: Requirements
└── Spec defines what, why, acceptance criteria

Phase 2: Design  
└── Agent proposes technical approach
└── Human reviews, adjusts

Phase 3: Implementation
└── Agent writes code following design
└── Hooks validate at each step

Phase 4: Verification
└── Acceptance criteria checked
└── Human approves

Benefit: Clear checkpoints, predictable outcomes, less rework.

Writing Good Acceptance Criteria

✅ Good Criteria (Specific, Testable)

- API returns 201 on successful creation
- Response includes id, createdAt, status fields
- Duplicate email returns 409 with error code USER_EXISTS
- Invalid email returns 400 with field-level errors
- Response time < 200ms for 95th percentile
- Rate limit: 100 requests/minute per API key

❌ Bad Criteria (Vague)

- API works correctly
- Good error handling
- Fast response
- Secure implementation

The Given-When-Then Format

Given a user with email "[email protected]" exists
When they request password reset
Then they receive email with valid reset link
And link expires in 1 hour
And token is stored securely (hashed)

Requirements Levels

Level 1: User Story

As a user, I want to reset my password
so that I can regain access if I forget it.

For human understanding, not agent execution.

Level 2: Feature Specification

Feature: Password Reset
- Generate secure token
- Send email with reset link
- Validate token on use
- Update password if valid

For planning and scope agreement.

Level 3: Technical Specification

Implementation:
1. POST /auth/forgot-password
   - Body: { email: string }
   - Generate: crypto.randomBytes(32)
   - Store: hash(token), userId, expiresAt
   - Send: email via EmailService
   - Return: 200 (always, for security)

2. GET /auth/reset-password?token=xxx
   - Validate token exists and not expired
   - Return: 200 if valid, 400 if invalid

3. POST /auth/reset-password
   - Body: { token: string, password: string }
   - Validate password strength
   - Update user password
   - Invalidate token
   - Return: 200 on success

For agent implementation.

Tools for Requirements

Structured Formats

• Markdown + YAML frontmatter: Human-readable, machine-parseable
• Gherkin (.feature files): Given-When-Then format
• JSON/YAML specs: Programmatic consumption

Requirements Management

• Linear: Issues as specs, integrate with agents
• Jira + AI plugins: Generate acceptance criteria
• Notion/Confluence: Living documentation
• Kiro: Native spec-driven development

AI-Assisted Requirements

Generating Acceptance Criteria

Input: "User can create an account"

AI generates:
- Email must be valid format
- Password minimum 8 characters
- Password must include uppercase, lowercase, number
- Duplicate email returns error
- Account created with pending status
- Verification email sent
- User can login after email verification

Identifying Edge Cases

Input: "Upload profile picture"

AI identifies:
- File size limit (5MB)
- Supported formats (jpg, png, webp)
- Image dimensions (min/max)
- Malicious file detection
- Storage failure handling
- Duplicate upload (same file)

Requirements Validation

AI reviews spec and flags:
- "Password reset link expires in 1 hour" → No mention of timezone
- "Rate limit: 100 requests" → Per user? Per IP? Global?
- "Secure implementation" → Not testable, needs specifics

Requirements to Code Workflow

Ideal Flow

1. Product defines problem
   ↓
2. AI helps draft acceptance criteria
   ↓
3. Human refines, adds constraints
   ↓
4. AI generates technical spec
   ↓
5. Engineer reviews, adjusts
   ↓
6. AI implements against spec
   ↓
7. AI generates tests from acceptance criteria
   ↓
8. Human validates against original problem

Checkpoint Reviews

Human gates prevent drift:

1. After acceptance criteria (does this solve the problem?)
2. After technical spec (is this the right approach?)
3. After implementation (does it meet criteria?)

Common Mistakes

🚩 Prescriptive Over Descriptive

❌ "Use Redux for state management"
✅ "State must be predictable, debuggable, work offline"

🚩 Implementation Leaks

❌ "Create users table with columns..."
✅ "Users must be stored with email, password hash, created at"

🚩 Missing Boundaries

❌ Feature spec with no "Out of Scope" section
✅ Explicit exclusions prevent scope creep

🚩 Untestable Requirements

❌ "Should be user-friendly"
✅ "Form submission completes in < 3 steps"

The Bottom Line

Good requirements for agentic coding:

• ✅ Clear about what success looks like
• ✅ Specific enough to verify
• ✅ Bounded (what's in, what's out)
• ✅ Contextual (why this matters)
• ✅ Constrained (technical limits)
• ✅ Referenced (existing patterns)

The agent can't read your mind. Write requirements as if explaining to a brilliant but literal intern.

Template: Feature Spec

## Feature: [Name]

### Problem Statement
[What problem does this solve?]

### Goals
- [Goal 1]
- [Goal 2]

### Non-Goals
- [Explicitly out of scope]

### Acceptance Criteria
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

### Technical Constraints
- [Technology/pattern requirements]
- [Performance requirements]

### References
- [Similar features]
- [Relevant documentation]
- [Design mockups]

### Open Questions
- [What needs clarification?]

Further Reading

• Agentic Coding: Architecture
• Agentic Coding: QA & Testing
• Agentic Coding: Best Practices