Skip to content

configuration.md

Latest commit

 

History

History
164 lines (129 loc) · 5.11 KB

configuration.md

File metadata and controls

164 lines (129 loc) · 5.11 KB

Configuration

AgentRC — prime your repositories for AI-assisted development.

AgentRC uses agentrc.config.json to define areas, workspaces, and policies for your repo. This file is optional for single-project repos — agentrc init creates it automatically when it detects a monorepo.

File location

Place agentrc.config.json at the repo root or in .github/. AgentRC checks both.

Schema

{
  "areas": [],
  "workspaces": [],
  "policies": [],
  "strategy": "flat",
  "detailDir": ".agents",
  "claudeMd": false
}

All fields are optional.

Areas

Areas are named slices of your codebase that get their own instructions. Each area has a glob pattern that scopes it to specific files:

{
  "areas": [
    { "name": "docs", "applyTo": "docs/**" },
    { "name": "api", "applyTo": "src/api/**", "description": "REST API layer" },
    { "name": "validation", "applyTo": ["src/validation/**", "src/schemas/**"] }
  ]
}
Field Type Required Description
name string yes Unique area identifier
applyTo string or string[] yes Glob pattern(s) relative to repo root
description string no Human description (used in generation)
parentArea string no Parent area name for hierarchical nesting

Generate area instructions with:

agentrc instructions --areas          # root + all areas
agentrc instructions --area docs      # single area
agentrc instructions --areas-only     # areas only, skip root

Per-area instructions map to VS Code's .instructions.md files with applyTo frontmatter. See File-based instructions in VS Code.

Workspaces

Workspaces model monorepo sub-projects. Each workspace groups areas scoped to a subdirectory:

{
  "workspaces": [
    {
      "name": "frontend",
      "path": "packages/frontend",
      "areas": [
        { "name": "app", "applyTo": "app/**" },
        { "name": "shared", "applyTo": ["shared/**", "common/**"] }
      ]
    },
    {
      "name": "backend",
      "path": "packages/backend",
      "areas": [
        { "name": "api", "applyTo": "src/api/**" },
        { "name": "workers", "applyTo": "src/workers/**", "parentArea": "api" }
      ]
    }
  ]
}
Field Type Required Description
name string yes Workspace identifier
path string yes Relative path from repo root
areas Area[] yes Areas scoped to this workspace

Key behaviors:

  • Area applyTo patterns are relative to the workspace path, not the repo root
  • Workspace areas get namespaced names: frontend/app, backend/api
  • Each workspace area gets its own workingDirectory for scoped eval sessions

Instruction strategy

Control how generated instructions are organized:

{
  "strategy": "nested",
  "detailDir": ".agents",
  "claudeMd": true
}
Field Default Description
strategy "flat" "flat" = single file, "nested" = hub + detail files
detailDir ".agents" Folder for detail files in nested strategy
claudeMd false Also generate CLAUDE.md alongside AGENTS.md (nested only)

CLI flags override config values: --strategy nested takes precedence.

Policies

Reference policy files to customize readiness scoring:

{
  "policies": ["./policies/strict.json"]
}

Paths are resolved relative to the current working directory. Only JSON policy files are allowed in config — TypeScript module policies must be passed via --policy on the command line.

See Policies for the policy authoring guide.

Full example

{
  "areas": [{ "name": "docs", "applyTo": "docs/**", "description": "Documentation" }],
  "workspaces": [
    {
      "name": "frontend",
      "path": "packages/frontend",
      "areas": [
        { "name": "app", "applyTo": "app/**" },
        { "name": "shared", "applyTo": ["shared/**", "common/**"] }
      ]
    },
    {
      "name": "backend",
      "path": "packages/backend",
      "areas": [
        { "name": "api", "applyTo": "src/api/**" },
        { "name": "workers", "applyTo": "src/workers/**", "parentArea": "api" }
      ]
    }
  ],
  "policies": ["./policies/strict.json"],
  "strategy": "flat"
}

See examples/agentrc.config.json for a working example.

Next steps

  • Policies — customize readiness scoring
  • Commands — CLI flags that override config values
  • Concepts — how areas and workspaces fit the maturity model