AI Specification Template

Thu, 19 Feb 2026 09:14:40 +1000

A structured template for specifying AI-assisted features, agent behaviours, or LLM-integrated components in a software project. Use this to document what the AI should do, how it should behave, and where the boundaries are.

The Template

# AI Specification: [Feature/Component Name]

## Overview

- **Purpose**: [One sentence — what does this AI component do?]
- **Model**: [e.g. Claude Sonnet 4.6, GPT-4o, local Llama 3]
- **Integration**: [e.g. API call, Claude Code agent, embedded SDK]
- **Owner**: [Team or person responsible]

## Behaviour

### Core Function

[Describe what the AI does in concrete terms. Focus on inputs, outputs,
and the transformation between them.]

- **Input**: [What the AI receives — e.g. user query, code diff, document]
- **Processing**: [What the AI does — e.g. summarise, classify, generate]
- **Output**: [What the AI produces — e.g. JSON response, text, code patch]

### Persona / System Prompt

[Define the AI's role, tone, and constraints at the system level.]

```
You are a [role] that [primary function].

Rules:
- [Constraint 1]
- [Constraint 2]
- [Tone/style guidance]
```

### Examples

#### Example 1: [Scenario Name]

**Input:**
[Sample input]

**Expected Output:**
[Sample output]

#### Example 2: [Edge Case]

**Input:**
[Edge case input]

**Expected Output:**
[How the AI should handle it]

## Boundaries

### Must Do

- [Required behaviour — e.g. "Always cite sources"]
- [Required behaviour — e.g. "Return valid JSON"]

### Must Not Do

- [Prohibited behaviour — e.g. "Never fabricate data"]
- [Prohibited behaviour — e.g. "Never expose internal system details"]

### Fallback Behaviour

[What happens when the AI cannot fulfil a request or encounters
an error. Define graceful degradation.]

- **Uncertain input**: [e.g. "Ask for clarification"]
- **Out of scope request**: [e.g. "Respond with a polite refusal"]
- **Model failure/timeout**: [e.g. "Return cached response or error message"]

## Data

### Input Data

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| [field] | [string/object/array] | [Yes/No] | [What it contains] |

### Output Schema

```json
{
  "result": "[description]",
  "confidence": "[0.0-1.0]",
  "metadata": {
    "model": "[model used]",
    "tokens_used": "[count]"
  }
}
```

### Context / RAG Sources

- [Document collection, database, or knowledge base the AI draws from]
- [How context is retrieved — e.g. vector search, keyword match]
- [Maximum context window budget allocation]

## Quality & Evaluation

### Success Criteria

| Metric | Target | Measurement |
|--------|--------|-------------|
| Accuracy | [e.g. >95%] | [How measured — e.g. human review, test suite] |
| Latency | [e.g. <2s p95] | [Monitoring tool or method] |
| Cost | [e.g. <$0.01/request] | [Token tracking method] |

### Test Cases

1. [Test description] → Expected: [outcome]
2. [Test description] → Expected: [outcome]
3. [Edge case test] → Expected: [outcome]

### Human Review

- **Review frequency**: [e.g. Weekly sample of 50 outputs]
- **Escalation path**: [When and how human review is triggered]
- **Feedback loop**: [How review results improve the system]

## Safety & Ethics

### Content Filtering

- [Pre-processing filters on input — e.g. PII detection]
- [Post-processing filters on output — e.g. toxicity check]

### Bias Considerations

- [Known bias risks for this use case]
- [Mitigation strategies]

### Audit Trail

- [What is logged — e.g. inputs, outputs, model version, timestamps]
- [Retention policy]
- [Access controls on logs]

## Implementation

### Architecture

```
[User/System] → [Pre-processing] → [Model API] → [Post-processing] → [Output]
```

### Configuration

| Parameter | Value | Notes |
|-----------|-------|-------|
| Model | [e.g. claude-sonnet-4-6] | [Why this model] |
| Temperature | [e.g. 0.3] | [Lower = more deterministic] |
| Max tokens | [e.g. 1024] | [Output length limit] |
| Top-p | [e.g. 0.9] | [Nucleus sampling threshold] |

### Dependencies

- [API keys / credentials needed]
- [SDKs or libraries — e.g. anthropic Python SDK]
- [Infrastructure — e.g. Redis for caching, vector DB for RAG]

### Cost Estimate

| Scenario | Requests/day | Avg tokens | Daily cost |
|----------|-------------|------------|------------|
| Low usage | [count] | [tokens] | [$amount] |
| Normal | [count] | [tokens] | [$amount] |
| Peak | [count] | [tokens] | [$amount] |

## Rollout

- [ ] Prototype with hardcoded examples
- [ ] Integration with real data source
- [ ] Internal testing (team review)
- [ ] Staged rollout (% of traffic)
- [ ] Full deployment
- [ ] Monitoring and alerting configured

Claude Code Prompt Template

Thu, 19 Feb 2026 09:14:40 +1000

A reusable template for writing structured prompts that get consistent, high-quality results from Claude Code. Copy the skeleton below and fill in each section for your task.

The Template

# [Task Title]

## Context

[Describe the project, codebase, or situation. Include relevant tech stack,
frameworks, and conventions. Reference specific files or directories.]

- Language/framework: [e.g. Python 3.12 / FastAPI]
- Key files: [e.g. `src/api/routes.py`, `tests/test_routes.py`]
- Conventions: [e.g. PEP 8, existing patterns to follow]

## Objective

[One or two sentences describing exactly what you want done.
Be specific about the desired outcome, not the steps.]

## Requirements

1. [Specific requirement with acceptance criteria]
2. [Another requirement]
3. [Constraint or boundary — e.g. "Do not modify the public API"]

## Current Behaviour

[What happens now. Include error messages, logs, or reproduction steps
if this is a bug fix.]

## Expected Behaviour

[What should happen after the change. Be precise.]

## Files Summary

| File | Action |
|------|--------|
| `path/to/file.py` | Modify — [brief description] |
| `path/to/new_file.py` | Create — [brief description] |
| `path/to/tests.py` | Update — [add tests for new behaviour] |

## Verification

1. [How to verify the change works — e.g. run a command, check output]
2. [Additional verification step]
3. [Edge case to test]

## Out of Scope

- [Things you explicitly do NOT want changed]
- [Adjacent improvements to skip for now]

Templates on Dustin Lee

AI Specification Template

The Template

Claude Code Prompt Template

The Template