# Best Practices for Structuring Configuration Files in Continue.dev

> Discover best practices for structuring Continue.dev configuration files. Learn how modular YAML files, a root continue.yaml, and JSON schema validation streamline your setup.

- Repository: [Continue/continue](https://github.com/continuedev/continue)
- Tags: best-practices
- Published: 2026-06-18

---

**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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/continue.yaml) or [`continue.json`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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:

```text
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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/openai.yaml), [`code-review.yaml`](https://github.com/continuedev/continue/blob/main/code-review.yaml)). The base name becomes the identifier when referenced from [`continue.yaml`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/rules/code-review.yaml), [`rules/security.yaml`](https://github.com/continuedev/continue/blob/main/rules/security.yaml)) and import them using the `include:` directive in the main file. The config loader in [`packages/config-yaml/src/index.ts`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/continue.yaml) or [`continue.json`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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:

```typescript
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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/continue.yaml) or [`continue.json`](https://github.com/continuedev/continue/blob/main/continue.json)) at the project root or `.continue/` directory that uses relative paths to reference fragments.
- **Validate early** against [`extensions/vscode/config_schema.json`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/continue.yaml) using relative paths or the `include:` directive. The loader in [`packages/config-yaml/src/index.ts`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/continue.yaml) (or [`continue.json`](https://github.com/continuedev/continue/blob/main/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`](https://github.com/continuedev/continue/blob/main/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.