Guide
How to Write Specifications for GitHub Copilot
The difference between “build a settings page” and a context-rich specification that gets the feature right on the first try.
Why Copilot needs better specifications
GitHub Copilot Agent can implement features from GitHub Issues. But the quality of the output depends entirely on the quality of the input. Vague issues produce generic code. Context-rich specifications produce features that align with your product strategy.
Vague specification
Title: Build settings page
Add a settings page where users can update their preferences.
Result: Generic settings page with wrong fields, no validation, no permission checks, doesn't match design system.
Agent specification
Title: Organization Settings Page
Vision: Self-service admin tools
Guardrails: Admin-only access
Success: 90% of setting changes self-served
AC: 8 testable scenarios with edge cases...
Result: Correct permissions, matching design system, proper validation, aligned with strategy.
The 5-part agent specification structure
A well-structured specification for GitHub Copilot includes five key sections. Each adds context that reduces ambiguity and improves implementation quality.
1. Product Context
Start with why this feature exists. Include your product vision statement and strategic guardrails.
Example:
Vision: Help product teams build the right things in the age of AI agents. Guardrail: All features must be accessible without requiring AI — AI enhances, never gates.
2. Discovery Insights
What has your team validated? Include customer needs, risk assessments, and tested assumptions.
Example:
Discovery: 87% of teams report >4 hours rework per AI-implemented feature due to missing context. Risk: Medium feasibility risk — requires new API endpoint.
3. Success Criteria (OKR-linked)
Define measurable outcomes connected to your team's objectives.
Example:
Key Result: Reduce average spec-to-implementation rework from 6 hours to 1.5 hours. This feature contributes to: O1 - Improve AI agent implementation quality.
4. Technical Context
Architecture patterns, API conventions, component libraries, and coding standards.
Example:
Stack: React 19, TypeScript, Tailwind CSS 4. Pattern: Use factory API service pattern. Auth: Wrap mutations in CanUpdate permission guard.
5. Acceptance Criteria
Precise, testable scenarios. Include happy paths, edge cases, error handling, and security.
Example:
Given: Admin user on Settings page. When: Changes org name to empty string. Then: Show validation error 'Organization name is required.' Button stays disabled.
Common pitfalls to avoid
Too vague
"Add user management" — Copilot doesn't know which users, what permissions, or what UI pattern.
Fix: Specify roles, permissions matrix, UI components, and validation rules.
No boundaries
Without guardrails, Copilot may over-engineer or build features that conflict with your strategy.
Fix: Include strategic guardrails: what NOT to build, what's out of scope.
Missing error cases
Specs that only cover happy paths lead to fragile implementations.
Fix: Include edge cases, error handling, loading states, and empty states.
No success criteria
Without metrics, it's impossible to evaluate if the implementation achieves its goal.
Fix: Link to OKR key results with measurable targets.
Automate with Delvyn Studio
Writing agent specifications manually is possible but time-consuming. Delvyn Studio generates them automatically from your structured product thinking:
- Define your product vision and strategic guardrails once
- Run structured discovery to validate ideas
- Set OKRs with measurable key results
- Generate agent specs that assemble all of this context automatically
- Push directly to GitHub Issues — Copilot Agent picks them up
- Capture learnings after implementation — future specs improve