Project planning
Planning is where staff engineers add the most value. Agents make implementation cheap, which makes over-building cheap too. The plan's job is to cut scope to the smallest slice that proves the riskiest assumption, and to surface one-way-door decisions before code exists.
Classify decisions first:
| Decision type | Examples | Process |
|---|---|---|
| One-way door | Data model, public API, vendor lock-in, auth design | ADR plus a reviewer outside the team |
| Two-way door | Internal module layout, library choice behind an interface | Decide and ship. Revisit if wrong |
Documents to create
| Document | Content | Who must read it |
|---|---|---|
| USER_STORIES.md | "As a [ROLE], I should be able to [feature]" | Product, team |
| DATA_MODELS.md | Schema, endpoint contracts | Every consuming team |
| TECH_STACK.md | Choices and the reasons for them | Future maintainers |
| DEVELOPMENT_PLAN.md | Phases, with the riskiest assumption first | Team, stakeholders |
| SECURITY_PLAN.md | Threats, data classification, controls | Security reviewer |
Example prompts:
USER_STORIES: "User stories for food delivery. Roles: customer, driver, restaurant, admin"
DATA_MODELS: "PostgreSQL schema from these stories. snake_case, timestamps, indexes"
TECH_STACK: "Tech stack for food delivery. Needs: real-time, payments, push, 10K users. Justify each choice"
DEV_PLAN: "3-phase plan. MVP: ordering+payment. Phase 2: tracking. Phase 3: analytics"
SECURITY_PLAN: "Security requirements: auth, PCI scope, location privacy, API security"Planning steps
- Describe the product and constraints to the agent. Ask what's unclear
- Generate user stories for every role
- Derive the schema from the stories
- Plan security early. Implement it with the feature
- Share the plan with dependent teams before implementation starts
- Generate the framework scaffolding
- Write the README and set up the repo
Example planning prompts:
Step 1: "SaaS invoicing for freelancers. Invoices, payments, reminders, reports. What's unclear?"
Step 2: "User stories: freelancer, client, accountant. Include partial payments, disputes"
Step 3: "DB schema for invoicing. Multi-currency, recurring, payment tracking. Show ERD"
Step 6: "Bootstrap Next.js + TS + Tailwind + Prisma + NextAuth. Feature-based folders"
Step 7: "README: overview, setup, env vars, contributing"Never ship an unreviewed AI plan. A plausible plan with a wrong premise costs more than no plan, because everyone builds on it.
Avoid premature optimization
Agents optimize early: retries, caching, rate limiting, and abstraction layers appear before the basics work. For each one ask "is this necessary for launch?" If not, add it to a FUTURE IMPROVEMENTS list with the trigger that would justify it.
Testing AI-generated code
AI-generated code needs more testing, not less, because it fails in ways human code usually doesn't.
What AI gets wrong:
| Issue | Example | How to catch |
|---|---|---|
| Hallucinated APIs | fs.readFileAsync() (doesn't exist) | Type check, run tests |
| Wrong assumptions | Assuming the user is always authenticated | Edge case tests |
| Incomplete logic | Missing null checks | Tests with null inputs |
| Off-by-one errors | i <= arr.length | Boundary tests |
| Race conditions | Async operations in the wrong order | Integration tests |
| Tests that assert nothing | expect(fn).not.toThrow() | Mutation testing, review |
Testing strategy:
1. Type check first (catches hallucinated APIs)
tsc --noEmit
2. Run existing tests (catches regressions)
bun test
3. Add tests for new behavior
"Write tests for the function you just created"
4. Smoke test by hand
Use the feature in the browser or CLI
5. Edge case sweep
"What edge cases could break this? Write tests for them."Testing prompts:
Before implementation:
"Write failing tests for this feature first. Cover the happy path, error cases,
and edge cases (empty input, null, very large values)."
Mutation check:
"If I changed this condition from < to <=, would any test fail?
If not, add a test that would."
Integration:
"Write an integration test covering the API call, the database write,
and the response."Measure what matters: coverage percent is easy for agents to inflate with weak assertions. Mutation score and the defects that reach production tell you whether the tests work.