Agent Configuration

Configure AI coding agents to work effectively with HarnSpec through AGENTS.md instructions and best practices.

AGENTS.md Overview

AGENTS.md serves as permanent instructions for AI coding agents in your repository. When you run harnspec init, this file is created with HarnSpec guidance.

Purpose:

Provide context about your project
Define when to use specs
Specify workflow and commands
Set quality standards

Agent Skills (SKILL.md)

HarnSpec now supports Agent Skills via a SKILL.md file. This is the preferred place to store SDD methodology so AGENTS.md can remain project-specific only.

Project skill location:

.github/skills/HarnSpec-sdd/SKILL.md (installed via harnspec skill install)

Why use a skill?

Cross-platform: works with Claude, Cursor, Codex, and other skill-compatible tools
Portable: checked into git and shared across projects
Minimal AGENTS.md: keep this file under 100 lines with only team-specific rules

Minimal AGENTS.md example (with skill):

# AI Agent Instructions

## Project: Example

Core SDD workflow is defined in .github/skills/HarnSpec-sdd/SKILL.md.

## Project-Specific Rules
- Use pnpm instead of npm
- Update both en and zh-CN locales for UI text

Multi-Tool Support

Different AI tools expect different instruction file names. HarnSpec automatically creates symlinks to ensure all tools find instructions:

AI Tool	Expected File	How HarnSpec Handles It
Claude Code / Claude Desktop	`CLAUDE.md`	Symlink → AGENTS.md
Gemini CLI	`GEMINI.md`	Symlink → AGENTS.md
GitHub Copilot	`AGENTS.md`	Primary file
Cursor	`AGENTS.md`	Primary file
Windsurf	`AGENTS.md`	Primary file
Droid	`AGENTS.md`	Primary file
Cline	`AGENTS.md`	Primary file
Kiro CLI	`AGENTS.md` / `.kiro/steering.md`	Primary file
Kimi CLI	`AGENTS.md`	Primary file
Qodo CLI	`AGENTS.md`	Primary file
Amp	`AGENTS.md`	Primary file
Trae Agent	`AGENTS.md`	Primary file
Qwen Code	`AGENTS.md`	Primary file
Warp Terminal	`AGENTS.md`	Primary file

HarnSpec Support Matrix

Tool	VibeKanban	OpenSpec Native	Agent Instructions File
Claude Code	✅	✅ (slash commands)	CLAUDE.md → AGENTS.md
OpenAI Codex	✅	✅ (slash commands)	AGENTS.md
GitHub Copilot	✅	✅ (slash commands)	AGENTS.md
Cursor	✅	✅ (slash commands)	AGENTS.md
OpenCode	✅	✅ (slash commands)	AGENTS.md
Qwen Code	✅	✅ (AGENTS.md)	AGENTS.md
Gemini CLI	✅	✅ (AGENTS.md)	GEMINI.md → AGENTS.md
Amp	✅	✅ (AGENTS.md)	AGENTS.md
Kiro CLI	✅	✅ (AGENTS.md)	AGENTS.md / .kiro/steering.md
Kimi CLI	✅	✅ (AGENTS.md)	AGENTS.md
Droid CLI	✅	✅ (AGENTS.md)	AGENTS.md
Qodo CLI	✅	✅ (AGENTS.md)	AGENTS.md
Trae Agent	✅	✅ (AGENTS.md)	AGENTS.md

Init Options

# Default: creates CLAUDE.md symlink (most common use case)
harnspec init -y

# Create symlinks for specific tools
harnspec init -y --agent-tools claude,gemini

# Create symlinks for all supported tools
harnspec init -y --agent-tools all

# Skip symlinks (legacy behavior)
harnspec init -y --agent-tools none

Note: On Windows, copies are created instead of symlinks (requires admin privileges).

CLI-First AGENTS.md

The generated AGENTS.md emphasizes CLI tools as the primary method for spec management:

Key Sections

1. Critical Discovery Steps

## 🚨 CRITICAL: Before ANY Task

**STOP and check these first:**

1. **Discover context** → Run `harnspec board` to see project state
2. **Search for related work** → Run `harnspec search` before creating new specs
3. **Never create files manually** → Always use `harnspec create` for new specs

2. CLI Commands as Primary Method

## 🔧 How to Manage Specs

### Primary Method: CLI Commands (Recommended)

HarnSpec provides a powerful CLI that you should **ALWAYS use** for spec management:

| Action | Command | Description |
|--------|---------|-------------|
| See project status | `harnspec board` | Kanban view + project health metrics |
| List all specs | `harnspec list` | Filterable list with metadata |
| Search specs | `harnspec search` | Semantic search across all content |
| View a spec | `harnspec view` | Full content with formatting |
| Create new spec | `harnspec create` | Auto-sequences, proper structure |
| Update spec | `harnspec update` | Validates transitions, timestamps |
| Check dependencies | `harnspec deps` | Visual dependency graph |

3. SDD Workflow Checkpoints

## ⚠️ SDD Workflow Checkpoints

### Before Starting ANY Task
1. 📋 **Run `board`** - What's the current project state?
2. 🔍 **Run `search`** - Are there related specs already?
3. 📝 **Check existing specs** - Is there one for this work?

### During Implementation
4. 📊 **Update status to `in-progress`** BEFORE coding
5. 📝 **Document decisions** in the spec as you work
6. 🔗 **Link related specs** if you discover connections

### After Completing Work
7. ✅ **Update status to `complete`** when done
8. 📄 **Document what you learned** in the spec
9. 🤔 **Create follow-up specs** if needed

4. Common Mistakes Table

### 🚫 Common Mistakes to Avoid

| ❌ Don't | ✅ Do Instead |
|----------|---------------|
| Create spec files manually | Use `create` tool |
| Skip discovery before new work | Run `board` and `search` first |
| Leave status as "planned" after starting | Update to `in-progress` immediately |
| Finish work without updating spec | Document decisions, update status |
| Edit frontmatter manually | Use `update` tool |
| Forget about specs mid-conversation | Check spec status periodically |

Complete AGENTS.md Template

# AI Agent Instructions

## Project: [Your Project Name]

[Brief description of what the project does]

## 🚨 CRITICAL: Before ANY Task

**STOP and check these first:**

1. **Discover context** → Run `harnspec board` to see project state
2. **Search for related work** → Run `harnspec search` before creating new specs
3. **Never create files manually** → Always use `harnspec create` for new specs

> **Why?** Skipping discovery creates duplicate work. Manual file creation breaks HarnSpec tooling.

## 🔧 How to Manage Specs

HarnSpec provides a powerful CLI that you should **ALWAYS use** for spec management:

| Action | Command | Description |
|--------|---------|-------------|
| See project status | `harnspec board` | Kanban view + project health metrics |
| List all specs | `harnspec list` | Filterable list with metadata |
| Search specs | `harnspec search` | Semantic search across all content |
| View a spec | `harnspec view` | Full content with formatting |
| Create new spec | `harnspec create` | Auto-sequences, proper structure |
| Update spec | `harnspec update` | Validates transitions, timestamps |
| Check dependencies | `harnspec deps` | Visual dependency graph |

## ⚠️ SDD Workflow Checkpoints

### Before Starting ANY Task
1. 📋 **Run `harnspec board`** - What's the current project state?
2. 🔍 **Run `harnspec search`** - Are there related specs already?
3. 📝 **Check existing specs** - Is there one for this work?

### During Implementation
4. 📊 **Update status to `in-progress`** BEFORE coding
5. 📝 **Document decisions** in the spec as you work
6. 🔗 **Link related specs** if you discover connections

### After Completing Work
7. ✅ **Update status to `complete`** when done
8. 📄 **Document what you learned** in the spec
9. 🤔 **Create follow-up specs** if needed

### 🚫 Common Mistakes to Avoid

| ❌ Don't | ✅ Do Instead |
|----------|---------------|
| Create spec files manually | Use `harnspec create` command |
| Skip discovery before new work | Run `harnspec board` and `search` first |
| Leave status as "planned" after starting | Update to `in-progress` immediately |
| Finish work without updating spec | Document decisions, update status |
| Edit frontmatter manually | Use `harnspec update` tool |
| Forget about specs mid-conversation | Check spec status periodically |

## Core Rules

1. **Read README.md first** - Understand project context
2. **Check specs/** - Review existing specs before starting
3. **Use HarnSpec CLI** - Treat CLI commands as your primary tools
4. **Follow HarnSpec principles** - Clarity over documentation
5. **Keep it minimal** - If it doesn't add clarity, cut it
6. **NEVER manually edit frontmatter** - Use CLI tools for updates
7. **Track progress in specs** - Update status and document decisions

## When to Use Specs

**Write a spec for:**
- Features affecting multiple parts of the system
- Breaking changes or significant refactors
- Design decisions needing team alignment

**Skip specs for:**
- Bug fixes
- Trivial changes
- Self-explanatory refactors

## Quality Standards

- **Status tracking is mandatory:**
  - `planned` → after creation
  - `in-progress` → BEFORE starting implementation
  - `complete` → AFTER finishing implementation
- Specs stay in sync with implementation
- Never leave specs with stale status

## Spec Complexity Guidelines

| Tokens | Status |
|--------|--------|
| <2,000 | ✅ Optimal |
| 2,000-3,500 | ✅ Good |
| 3,500-5,000 | ⚠️ Consider splitting |
| >5,000 | 🔴 Should split |

Use `tokens` tool to check spec size.

Configuring Different AI Tools

Claude Code

Claude Code reads CLAUDE.md by default. HarnSpec automatically creates this symlink:

# After harnspec init
ls -la CLAUDE.md
# CLAUDE.md -> AGENTS.md

With Agent Skills (Recommended): Use AGENTS.md and SKILL.md for full functionality. See Agent Configuration.

Gemini CLI

Gemini CLI reads GEMINI.md. Create with:

harnspec init -y --agent-tools gemini

GitHub Copilot

Copilot automatically reads AGENTS.md when files are opened in your editor.

No additional setup needed.

Cursor

Cursor reads .cursorrules by default. Options:

Option 1: Use AGENTS.md (recommended)

# Cursor also reads AGENTS.md
# No additional setup

Option 2: Link .cursorrules to AGENTS.md

ln -s AGENTS.md .cursorrules

Windsurf

Windsurf reads AGENTS.md by default. No additional setup needed.

Best Practices for AI-Readable Specs

1. Be Explicit and Concrete

❌ Vague:

Implement secure authentication

✅ Specific:

Implement JWT authentication with:
- bcrypt password hashing (min 10 rounds)
- 24-hour token expiry
- Rate limiting (5 attempts/min per IP)

2. Provide Examples

AI agents understand examples better than abstract descriptions.

Good:

## API Response Example

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2025-11-03T06:00:00Z",
  "user": {
    "id": "user_123",
    "email": "user@example.com"
  }
}

### 3. Use Testable Acceptance Criteria

Make criteria specific and verifiable:

✅ **Good Criteria:**
- [ ] POST /api/auth/login returns 200 with JWT on success
- [ ] Invalid credentials return 401 with error message
- [ ] Passwords are hashed with bcrypt, min 10 rounds
- [ ] Rate limit: max 5 attempts per minute per IP

❌ **Bad Criteria:**
- [ ] Authentication works
- [ ] Good security
- [ ] Fast performance

### 4. Define Boundaries Explicitly

Use "Out of Scope" or "Non-Goals" to prevent scope creep:

```markdown
## Out of Scope

- Social login (Google, GitHub) - separate epic
- Password reset - separate spec
- 2FA - not needed for MVP
- Remember me functionality - future enhancement

5. Show, Don't Just Tell

Include concrete examples of:

API requests/responses
CLI commands and output
Database schemas
Configuration files
Test cases

6. Structure for Scanning

AI agents (and humans) scan before reading:

✅ Good Structure:

## Problem
[2-3 sentences]

## Solution
[High-level approach]

### Technical Details
[Implementation specifics]

## Success Criteria
- [ ] [Testable outcome]

❌ Bad Structure:

So we need to build this feature and it should do X, Y, Z...
[wall of text with no structure]

Repository Organization

Make Specs Discoverable

your-project/
├── AGENTS.md           ← Primary AI instructions
├── CLAUDE.md → AGENTS.md   ← Symlink for Claude Code
├── README.md           ← Project overview
├── specs/              ← All specs here
│   ├── 001-feature-a/
│   │   └── README.md
│   ├── 002-feature-b/
│   │   ├── README.md
│   │   ├── DESIGN.md
│   │   └── TESTING.md
│   └── archived/       ← Old specs
├── src/                ← Source code
└── tests/              ← Tests

Keep Specs Close to Code

Specs in the repo (not external wiki):

✅ Version controlled
✅ Branch-specific
✅ Easy for AI to find
✅ Searchable

Verification

Test AI Understanding

Ask your AI agent these questions to verify HarnSpec integration:

Test 1: Can it discover the project?

Show me the project board.

Expected: Agent runs harnspec board

Test 2: Can it search specs?

Find specs related to authentication.

Expected: Agent runs harnspec search "authentication"

Test 3: Can it create specs properly?

Create a spec for user authentication.

Expected: Agent runs harnspec create (NOT manual file creation)

Test 4: Can it update status?

Mark spec 001 as in-progress.

Expected: Agent runs harnspec update 001 --status in-progress

Test 5: Does it follow SDD workflow?

I want to implement a new caching feature.

Expected: Agent first runs board and search, then creates spec before coding

Common Pitfalls

1. Overly Verbose Instructions

❌ Bad:

The AI agent should carefully read all available documentation
and thoroughly understand the codebase before making any changes.
It's important to...
[500 words of general advice]

✅ Good:

Read README.md first
Check existing specs with `harnspec list`
Follow HarnSpec principles (see AGENTS.md)

2. Ambiguous Success Criteria

❌ Bad:

- [ ] Feature works well
- [ ] Good performance
- [ ] Users are happy

✅ Good:

- [ ] API response `<100`ms (p95)
- [ ] Zero crashes in 1 week
- [ ] NPS score >8

3. Missing Context

Always provide:

Why: Problem and motivation
What: Specific requirements
How: Approach and constraints
When: Success criteria

Next Steps

CLI Reference - Complete command documentation
AI-Assisted Spec Writing - Practical patterns
Getting Started - Initial setup guide

Related: CLI Reference for complete command documentation

AGENTS.md Overview​

Agent Skills (SKILL.md)​

Multi-Tool Support​

HarnSpec Support Matrix​

Init Options​

CLI-First AGENTS.md​

Key Sections​

1. Critical Discovery Steps​

2. CLI Commands as Primary Method​

3. SDD Workflow Checkpoints​

4. Common Mistakes Table​

Complete AGENTS.md Template​

Configuring Different AI Tools​

Claude Code​

Gemini CLI​

GitHub Copilot​

Cursor​

Windsurf​

Best Practices for AI-Readable Specs​

1. Be Explicit and Concrete​

2. Provide Examples​

5. Show, Don't Just Tell​

6. Structure for Scanning​

Repository Organization​

Make Specs Discoverable​

Keep Specs Close to Code​

Verification​

Test AI Understanding​

Common Pitfalls​

1. Overly Verbose Instructions​

2. Ambiguous Success Criteria​

3. Missing Context​

Next Steps​