Agent Instructions¶

Agent instructions are markdown documents that tell AI agents how to work within your project. They define coding standards, architectural patterns, testing requirements, and any project-specific rules your agents should follow.

Overview¶

FuncSpec supports agent instructions at two levels:

Level	Scope	Use Case
Organization	All projects in the org	Company-wide standards, coding style, security policies
Project	Single project	Project-specific architecture, tech stack, conventions

Instructions resolve with a fallback chain: project → organization → default template. If a project has no instructions, the org-level instructions are used. If neither exists, FuncSpec provides a sensible default template.

Writing Instructions¶

Good agent instructions are specific, actionable, and organized. Here's what to include:

Project Context¶

## Project Overview
This is a Rails 8 API application using PostgreSQL, Solid Queue for 
background jobs, and Kamal for deployment.

## Tech Stack
- Ruby 3.3 / Rails 8
- PostgreSQL 16
- Stimulus + Turbo for frontend
- RSpec for testing

Coding Standards¶

## Code Style
- Follow existing patterns in the codebase
- Use service objects for complex business logic
- Keep controllers thin — delegate to models or services
- All new endpoints need request specs

## Naming Conventions
- Models: singular (User, Project)
- Controllers: plural (UsersController)
- Service objects: verb-noun (CreateSubscription, SyncRepository)

Testing Requirements¶

## Testing
- Every new feature needs request specs
- Every bug fix needs a regression test
- Run the full test suite before marking as implemented
- Minimum test command: `bin/rails test`

Architecture Rules¶

## Architecture
- API endpoints go in app/controllers/api/v1/
- All API responses use the JSON envelope format: { data: { ... } }
- Background jobs inherit from ApplicationJob
- Use Solid Queue for all async work — no Sidekiq

Things to Avoid¶

## Don't
- Don't add new gems without approval
- Don't modify the deployment configuration
- Don't change database schema without a migration
- Don't bypass authorization checks

Managing Instructions¶

Via the Web UI¶

Go to your project page
Click Settings → Agent Instructions
Write or edit your instructions in the markdown editor
Click Save

For org-level instructions: 1. Go to Organization Settings → Agent Instructions 2. These apply to all projects that don't have their own instructions

Via the API¶

Read instructions (public endpoint — no auth required):

# Get instructions as JSON
curl "https://funcspec.net/api/v1/projects/my-project/agent_instructions"

# Get instructions as raw markdown (better for feeding to agents)
curl "https://funcspec.net/api/v1/projects/my-project/agent_instructions?format=markdown"

Update project instructions:

curl -X PATCH -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "## Project Rules\n\nAlways write tests first.\n"}' \
  "https://funcspec.net/api/v1/projects/my-project/agent_instructions"

Update org-level instructions:

curl -X PATCH -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "## Company Standards\n\nAll code must pass linting.\n"}' \
  "https://funcspec.net/api/v1/agent_instructions"

Via the CLI¶

# View current instructions
funcspec config get agent-instructions

# The CLI reads agent instructions automatically when running AI operations

Version History¶

Every time instructions are updated, FuncSpec saves the previous version. This lets you:

Track changes over time
Correlate instruction changes with agent behavior
Roll back if a change caused problems

List versions:

curl -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  "https://funcspec.net/api/v1/projects/my-project/agent_instructions/versions"

Response:

{
  "data": [
    {"id": 5, "version": 3, "updated_by": "narbs@example.com", "created_at": "2026-03-31T18:00:00Z"},
    {"id": 4, "version": 2, "updated_by": "narbs@example.com", "created_at": "2026-03-28T14:30:00Z"},
    {"id": 3, "version": 1, "updated_by": "narbs@example.com", "created_at": "2026-03-15T10:00:00Z"}
  ]
}

View a specific version:

curl -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  "https://funcspec.net/api/v1/projects/my-project/agent_instructions/versions/2"

Tracking instruction versions in agent runs:

When recording an agent run, include the instruction_version field:

curl -X POST -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_key": "agent-session-abc",
    "model": "claude-sonnet-4-20250514",
    "provider": "anthropic",
    "status": "completed",
    "instruction_version": 3
  }' \
  "https://funcspec.net/api/v1/projects/my-project/work_package/T-42/record_run"

This creates a clear audit trail: you can see exactly which instructions each agent was following.

Fallback Chain¶

When an agent requests instructions, FuncSpec resolves them in order:

1. Project-level instructions (if set)
   ↓ (not found)
2. Organization-level instructions (if set)
   ↓ (not found)
3. Default template

The response includes a scope field telling you which level was used:

{
  "data": {
    "type": "agent_instruction",
    "attributes": {
      "content": "## Your Instructions...",
      "version": 3,
      "scope": "project",
      "updated_at": "2026-03-31T18:00:00Z",
      "updated_by": "narbs@example.com"
    }
  }
}

Possible scope values:

Scope	Meaning
`project`	Project-specific instructions
`org`	Organization-level default
`default`	Built-in template (no custom instructions set)

Public Access¶

The GET endpoint for agent instructions is publicly accessible — no API key required. This makes it easy for any agent or CI system to fetch instructions without managing credentials.

Why Public?

Agent instructions are typically coding standards and conventions — not sensitive data. Making them public means any agent (GitHub Actions, CI runners, local scripts) can fetch them without API key setup. If you need instructions private, set up authentication.

If you do authenticate, the response may include additional context based on your permissions.

Tips¶

Start Simple

You don't need pages of instructions on day one. Start with your tech stack and testing requirements. Add rules as you discover what agents get wrong.

Be Specific

"Write good tests" is too vague. "Every new controller action needs a request spec that tests success, auth failure, and validation error cases" is actionable.

Include Examples

Show agents what good looks like. Include a snippet of a well-structured test or a properly formatted API response.

Update After Issues

When an agent makes a mistake, add a rule to prevent it. Agent instructions are a living document — update them as you learn.