Best Practices for Structuring Configuration Files in Continue.dev

Continue.dev employs a modular, convention-driven configuration architecture that separates models, agents, prompts, and rules into distinct YAML files, anchored by a root continue.yaml entry point and strictly validated against a JSON schema.

The Continue.dev open-source AI assistant uses the @continuedev/config-yaml package to manage configuration, implementing a deterministic loader that discovers, merges, and validates configuration fragments across your project tree. Adhering to the repository's structural conventions ensures reproducible AI-assisted workflows across local development environments, collaborator machines, and CI pipelines.

Core Principles of Continue Configuration

Separate Concerns

Configuration files in Continue.dev isolate distinct functional areas into dedicated documents. Rule definitions live separately from agent configurations, preventing tightly coupled definitions that become difficult to maintain. For example, the test file at packages/config-yaml/src/__tests__/test-files/invokable-rules.yaml demonstrates a standalone rule set, while packages/config-yaml/src/__tests__/packages/test-org/agent.yaml contains an isolated agent definition. This separation allows teams to update prompt logic without touching model provider settings.

Top-Level Entry Point

Every Continue.dev project requires a single root configuration file—either continue.yaml or continue.json—located at the project root or inside a .continue/ directory. This entry point references other configuration fragments via relative paths. The repository's worktree-config.yaml demonstrates this pattern, showing how the root file acts as a manifest that imports specialized configurations from subdirectories. This approach makes the entire configuration portable across file systems because all references are relative to the config root.

Schema-Validated Structure

All configuration files must conform to the JSON schema defined in extensions/vscode/config_schema.json. This schema declares strict sections for models, agents, prompts, and rules, each with required fields and type constraints. The VS Code extension and CLI both import this schema to provide early validation feedback. Because the schema enforces structure at parse time, runtime errors caused by malformed configurations are eliminated before the LLM session begins.

Recommended Directory Layout

Organize your Continue.dev configuration using a hierarchical directory structure that mirrors the separation of concerns:

my-project/
├─ .continue/                     # optional hidden folder

│   ├─ continue.yaml               # top-level entry point

│   ├─ models/
│   │   └─ openai.yaml             # model provider config

│   ├─ agents/
│   │   └─ default-agent.yaml      # agent definition

│   ├─ prompts/
│   │   └─ my-prompt.yaml          # prompt templates

│   └─ rules/
│       └─ code-review.yaml        # rule set for invocations

└─ src/                           # source code of your own project

Place the continue.yaml entry point at the root of .continue/ or your project directory, then store specialized fragments in categorized subdirectories. This layout keeps version control diffs readable and allows developers to locate specific configuration domains quickly.

Key File Naming and Organization Conventions

Follow these five conventions to maintain portable, maintainable configurations:

1. Use lower-kebab-case file names – Name files with lowercase words separated by hyphens and use the .yaml extension (e.g., openai.yaml, code-review.yaml). The base name becomes the identifier when referenced from continue.yaml.

2. Reference files with relative paths – Never use absolute paths in the top-level configuration file. Relative paths ensure the configuration works across different machines and containerized CI environments without modification.

3. Ship version-controlled defaults – Include a minimal continue.yaml with sensible defaults (such as the built-in default agent) in your repository. Users can copy and extend this template rather than editing internal defaults, preventing merge conflicts during upgrades.

4. Validate against the schema – Run npx continue validate-config or use the VS Code extension to check files against extensions/vscode/config_schema.json before committing. The validator reports errors with specific file and line numbers, catching type mismatches and missing required fields early.

5. Modularize large configurations – Split complex rule sets into multiple files (e.g., rules/code-review.yaml, rules/security.yaml) and import them using the include: directive in the main file. The config loader in packages/config-yaml/src/index.ts handles merging these fragments deterministically.

How the Configuration Loader Works

The @continuedev/config-yaml package implements a three-phase loading process that ensures consistent runtime behavior:

Discovery Phase

The loader walks the directory tree starting from the entry point location (continue.yaml or continue.json). It identifies all referenced YAML files through relative path declarations and include: directives, building a complete manifest of configuration fragments.

Parsing and Merging

Each discovered file is parsed using js-yaml and merged into a single configuration object. The merge strategy preserves the hierarchy defined in your directory structure, with later imports overriding earlier declarations when conflicts occur.

Validation

The merged configuration object is validated against extensions/vscode/config_schema.json. Validation errors are reported with precise file paths and line numbers, allowing developers to debug malformed configurations before they reach the LLM inference stage. Because this process is deterministic, identical file trees produce identical runtime configurations—essential for reproducible AI-assisted development.

Loading Configurations Programmatically

Access the configuration system directly from Node.js scripts using the loadConfig function exported by @continuedev/config-yaml. This is useful for testing, custom tooling, or CI validation pipelines:

import { loadConfig } from '@continuedev/config-yaml';

async function getConfig() {
  // Assumes a `continue.yaml` at the project root
  const cfg = await loadConfig({ cwd: process.cwd() });
  console.log('Loaded models:', cfg.models);
  console.log('Active agent:', cfg.agents?.[0]?.name);
  return cfg;
}

getConfig().catch(err => console.error('Config error:', err));

The loadConfig implementation in packages/config-yaml/src/index.ts handles discovery, parsing, and schema validation automatically, throwing detailed errors if the configuration violates the schema defined in extensions/vscode/config_schema.json.

Summary

• Separate concerns by storing models, agents, prompts, and rules in distinct YAML files within categorized subdirectories.
• Maintain a single entry point (continue.yaml or continue.json) at the project root or .continue/ directory that uses relative paths to reference fragments.
• Validate early against extensions/vscode/config_schema.json using npx continue validate-config or the VS Code extension to catch errors before runtime.
• Use lower-kebab-case naming and relative paths exclusively to ensure portability across development environments.
• Leverage modularity via the include: directive to break large configurations into maintainable fragments, merged deterministically by the loader in packages/config-yaml/src/index.ts.

Frequently Asked Questions

What file format should I use for Continue.dev configuration files?

Continue.dev supports both YAML and JSON formats, but YAML is the recommended format for user-editable configuration files. Use the .yaml extension with lower-kebab-case naming (e.g., my-agent.yaml). The YAML parser in @continuedev/config-yaml preserves comments and handles multi-line strings better than JSON, making it ideal for complex prompt definitions and rule sets.

How does Continue.dev validate my configuration files?

Continue.dev validates configurations against the JSON schema located at extensions/vscode/config_schema.json. The VS Code extension performs real-time validation as you edit, while the CLI command npx continue validate-config checks files programmatically. The validator ensures required fields like models and agents contain correct types and flags unknown properties, preventing runtime errors during LLM inference.

Can I split my configuration across multiple files?

Yes, Continue.dev encourages modular configurations. Place fragments in subdirectories like models/, agents/, or rules/, then reference them from your root continue.yaml using relative paths or the include: directive. The loader in packages/config-yaml/src/index.ts discovers and merges these files deterministically, allowing teams to manage large rule sets or agent definitions without maintaining monolithic configuration files.

Where should I place the main configuration file in my project?

Place the main continue.yaml (or continue.json) at your project root or inside a .continue/ directory at the root. This location serves as the discovery entry point for the config loader. The repository's worktree-config.yaml demonstrates this pattern, showing how the top-level file acts as a manifest that imports other configuration fragments using relative paths, ensuring the setup remains portable across different machines.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}