Expert Specification Bot

Your agent for creating detailed technical specifications, requirements documents, and system design specs — transforming high-level ideas into comprehensive, implementable specifications.

When to Use This Agent

Choose Expert Specification Bot when:

• Writing technical specifications for new features or systems
• Creating detailed requirements documents from stakeholder input
• Defining API contracts, data schemas, and integration specifications
• Producing system design documents with component interactions
• Standardizing specification formats across engineering teams

Consider alternatives when:

• You need implementation plans (step-by-step coding) — use a planner agent
• You need architecture design — use an architect agent
• You need Jira ticket creation — use an Atlassian agent

Quick Start

Copy
# .claude/agents/specification.yml
name: Expert Specification Bot
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Technical specification agent for creating detailed requirements, system designs, and API contracts

Example invocation:

claude "Write a technical specification for a real-time notification system — cover system architecture, API endpoints, WebSocket protocol, data models, and delivery guarantees"

Core Concepts

Specification Document Structure

Copy
# Technical Specification: [Feature Name]

## 1. Overview
- Problem statement
- Proposed solution (1-2 paragraphs)
- Success criteria

## 2. Requirements
### Functional Requirements
### Non-Functional Requirements (performance, security, scale)
### Out of Scope

## 3. System Design
### Architecture diagram
### Component descriptions
### Data flow

## 4. API Specification
### Endpoints
### Request/response schemas
### Error codes

## 5. Data Model
### Schema definitions
### Relationships
### Migration plan

## 6. Security Considerations
## 7. Testing Strategy
## 8. Rollout Plan
## 9. Open Questions

Specification Quality Metrics

Metric	Good Spec	Bad Spec
Completeness	All components specified	"Details TBD" scattered throughout
Testability	Clear acceptance criteria	Vague "it should work well"
Precision	Specific numbers, formats	"Fast response times"
Scope	Clear boundaries	Scope creep built in
Feasibility	Grounded in current system	Ignores existing constraints

Configuration

Parameter	Description	Default
spec_type	Specification type (feature, api, system, integration)	feature
detail_level	Specification depth (overview, standard, exhaustive)	standard
include_diagrams	Include architecture diagrams	true
include_api_spec	Include API endpoint definitions	true
include_data_model	Include data schema definitions	true

Best Practices

1. Start with the "why" before the "what." The problem statement should make any reader understand why this specification exists. If someone can't articulate the problem after reading the overview, the spec isn't ready.

2. Define "out of scope" explicitly. What you won't do is as important as what you will do. Explicitly listing out-of-scope items prevents scope creep and alignment issues. "This spec does NOT cover offline support, multi-tenancy, or data export."

3. Use concrete examples for every abstract requirement. "The API should return paginated results" is abstract. "GET /users?page=2&size=20 returns { data: [...20 users...], meta: { page: 2, totalPages: 5, totalItems: 100 } }" is concrete and testable.

4. Include non-functional requirements with specific targets. "The system should be fast" is unmeasurable. "API p99 latency under 200ms at 1000 RPS, 99.9% availability measured monthly, supporting up to 10K concurrent WebSocket connections" is verifiable.

5. Separate specification from implementation detail. The spec says "the system stores user preferences" — it doesn't say "use a PostgreSQL JSONB column." Specifications define contracts and behaviors; implementation details belong in the implementation plan.

Common Issues

Spec is too abstract to implement. "The system handles authentication" doesn't tell engineers what to build. Specify: which auth protocols (OAuth 2.0, SAML), which flows (authorization code, client credentials), which token format (JWT), and which token storage (httpOnly cookies).

Stakeholders approve the spec without reading it. Long specs with dense prose get rubber-stamped. Use executive summaries, visual diagrams, and highlighted key decisions. Call out sections that need explicit stakeholder input.

Spec becomes outdated during implementation. Treat specs as living documents. Update them when implementation reveals that the original design doesn't work. Mark the spec as "superseded" when the system diverges significantly.