AI Integration Setup

Backlog.md supports two AI integration modes: MCP protocol (recommended) and CLI instruction files.

MCP Protocol (recommended)

MCP (Model Context Protocol) allows AI agents to invoke Backlog.md tools directly, without users typing CLI commands manually.

Claude Code

claude mcp add backlog --scope user -- backlog mcp start

OpenAI Codex

codex mcp add backlog -- backlog mcp start

Codex uses -- as the stdio command separator.

Google Gemini CLI

gemini mcp add backlog -s user backlog mcp start

Kiro

kiro-cli mcp add --scope global --name backlog --command backlog --args mcp,start

Cursor

Manually configure mcpServers and add:

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "start"]
    }
  }
}

CLI instruction mode: Cursor also reads the project root AGENTS.md as a general agent instruction file. When running backlog init or backlog agents --update-instructions, Cursor instructions are written to AGENTS.md; no separate .cursorrules file is generated.

CLI Instruction Files

For AI tools that do not support MCP, Backlog.md can generate agent instruction files that guide the AI on how to use backlog commands.

Generate Instruction Files

Choose CLI instruction mode during backlog init, or run later:

backlog agents --update-instructions

This generates:

• CLAUDE.md — Claude Code / Claude Desktop
• AGENTS.md — generic agent instructions (Cursor also reads this file)
• GEMINI.md — Gemini CLI
• .github/copilot-instructions.md — GitHub Copilot

Re-running backlog init or backlog agents --update-instructions preserves existing AGENTS.md content; Backlog.md only updates its marked blocks.

Instruction File Contents

The files include workflow guides, task creation conventions, acceptance-criteria formats, and other rules so the AI knows how to:

• Create tasks with acceptance criteria
• Use backlog commands to manage the task lifecycle
• Follow project conventions (branch naming, commit format, etc.)

Integration Mode Comparison

Recommended AI Workflow

Step 1: Describe the Idea

Tell the AI agent what you want to build, and let it break the work into small tasks, each with a clear description and acceptance criteria.

Step 2: One Task at a Time

Handle one task per agent session, one task per PR. Make sure each task is small enough to complete within a single conversation.

Step 3: Write a Plan Before Coding

Before implementation, ask the agent to study the codebase and write an implementation plan in the task.

Step 4: Implement and Verify

Have the agent implement the task. After completion, review the code, run tests, and check lint to verify the result.

Restart Loop When Unsatisfied

Clear the plan/notes/final summary, refine the task description and acceptance criteria, and rerun in a new session.