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:

  1. 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.
  2. Memory config (CLAUDE, AGENTS, .cursorrules): project conventions, instructions, durable context the harness reads into the system prompt. Markdown.
  3. 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:

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

For memory files, the harness usually walks up from the cwd collecting every CLAUDE 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.

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 / FrameworkBehavior configMemory fileExtension dir
Claude Code.claude/settings.json (+local + user)CLAUDE (walk-up).claude/agents/, .claude/commands/, .claude/skills/
Claude Agent SDKProgrammaticPluggableProgrammatic
rufloInherits Claude Code + plugin manifestsCLAUDE + .ruflo/memory.claude-plugin/plugin.json per plugin
LangGraphCode-onlyCode-onlyCode-only
AutoGenMostly code; some YAML configsDIYDIY
CrewAIYAML for agents/tasks (optional)DIYYAML
OpenAI Agents SDKCode-onlyDIYCode-only
Codex CLI~/.codex/config.tomlAGENTSLimited
Cursor~/.cursor/settings.json + workspace.cursorrulesLimited extension API

Connections to Other Concepts

Further Reading

  • Anthropic, Claude Code settings.json reference.
  • ruvnet, ruflo USERGUIDE — a working example of a deeply configured harness.