Settings and Configuration Files

One-Line Summary: A harness's configuration files (settings.json, CLAUDE.md, .cursorrules, .ruflo/config.toml) are its public API — the user-editable contract through which extensions, permissions, hooks, and memory are declared; their format and merge semantics matter as much as any code in the harness.

Prerequisites: What is an AI harness, hooks and lifecycle events

What Are Harness Configuration Files?

Every meaningful harness exposes its behavior through one or more files the user edits directly. These files are not implementation details — they are the public surface, and changing them is a breaking change in the same sense an API change is. Three categories:

Behavior config (settings.json in Claude Code, ~/.cursor/settings.json in Cursor): hooks, allowed tools, model selection, MCP servers, output format. Usually JSON or TOML.
Memory config (CLAUDE.md, AGENTS.md, .cursorrules): project conventions, instructions, durable context the harness reads into the system prompt. Markdown.
Extension definitions (.claude/agents/, .claude/commands/, .claude/skills/, .claude-plugin/plugin.json): sub-agents, slash commands, skills, plugin manifests. Mix of markdown and JSON.

How They're Loaded

A typical harness loads configuration in layered order, with later layers overriding earlier ones:

Built-in defaults (compiled into the harness).
User-global (~/.claude/settings.json).
Project-local (.claude/settings.json).
Local override (.claude/settings.local.json, gitignored).
CLI flags at invocation time.

For memory files, the harness usually walks up from the cwd collecting every CLAUDE.md along the way and concatenates them; the concatenated result becomes part of the system prompt for the session.

Why It Matters

Configuration files are how a team encodes its agent policy. They are how a project's conventions get applied automatically. They are how plugins ship behavior. They are also a stability commitment — once published, the config schema is hard to change without breaking users. Treat the schema with the seriousness you'd treat a public API.

A subtle but important property: configuration is the portability mechanism. The fastest way to share an agent setup with a teammate is to push .claude/ to the repo. The fastest way to onboard a new project to an agentic workflow is to copy a known-good CLAUDE.md.

Key Technical Details

Merge strategies vary: Some harnesses do shallow merge (later layer replaces earlier object); others do deep merge (layer arrays concatenate, objects merge recursively). Read the docs.
Secrets do not belong in config: Configuration is checked into git by default; secrets must be referenced via env vars or a secrets manager.
Hooks reference executables by path: Configuration paths are usually relative to the config file's location, not the cwd, so hooks don't break when invoked from subdirectories.
Invalid config typically fails open with a warning, not closed: Harnesses prioritize "the agent runs" over strict validation. This is a usability choice; it can also be a security risk.
Schema versioning: Mature harnesses include a version field; older harnesses are still figuring out migration story.
local files are gitignored: A common pattern is settings.json (committed) and settings.local.json (gitignored, machine-specific overrides).

How Harnesses & Frameworks Implement This

Harness / Framework	Behavior config	Memory file	Extension dir
Claude Code	`.claude/settings.json` (+local + user)	`CLAUDE.md` (walk-up)	`.claude/agents/`, `.claude/commands/`, `.claude/skills/`
Claude Agent SDK	Programmatic	Pluggable	Programmatic
ruflo	Inherits Claude Code + plugin manifests	`CLAUDE.md` + `.ruflo/memory`	`.claude-plugin/plugin.json` per plugin
LangGraph	Code-only	Code-only	Code-only
AutoGen	Mostly code; some YAML configs	DIY	DIY
CrewAI	YAML for agents/tasks (optional)	DIY	YAML
OpenAI Agents SDK	Code-only	DIY	Code-only
Codex CLI	`~/.codex/config.toml`	`AGENTS.md`	Limited
Cursor	`~/.cursor/settings.json` + workspace	`.cursorrules`	Limited extension API

Connections to Other Concepts

hooks-and-lifecycle-events.md — Hooks are declared in settings.
permission-and-tool-scoping-primitives.md — Permissions live in settings.
plugin-and-marketplace-systems.md — Plugins extend the configuration surface.
harness-owned-memory.md — Memory files are configuration files.
memory-portability-across-harnesses.md — Cross-harness memory portability via configuration.