Lean Claude Code Harness

Distill the durable parts of Claude Code into a smaller, auditable harness. The goal is not feature parity. The goal is a runtime another engineer can understand, extend, and verify without reverse-engineering hidden behavior.

When to Use

Use this skill when a coding-agent runtime shows any of these symptoms:

• config values are hard to trace
• tool permissions are implicit or inconsistent
• the tool surface keeps growing without clear ownership
• session history disappears after a run
• the main loop is hard to sketch from memory
• product-only logic is mixed into the harness core

Keep These Primitives

• layered configuration
• permission-aware tool execution
• a small explicit tool registry
• markdown skill discovery
• transcript persistence
• a visible query loop

Remove These By Default

• telemetry
• remote-managed settings
• hidden kill-switches
• private feature flags
• branding-specific branches
• heavyweight UI layers

Only add them back when the user explicitly asks for them and can explain the operational need.

Quick Audit

If you need a fast harness review, answer these six questions first:

1. Can you explain config precedence without reading three files?
2. Are tool permissions checked before execution?
3. Can you list the built-in tools in one screen?
4. Are skills discovered from visible files instead of hidden registration?
5. Does every run persist a transcript?
6. Can you trace the query loop from prompt to final response?

If two or more answers are "no", the harness is already too opaque.

Apply This Order

1. Freeze the Runtime Boundary

Keep the entrypoint thin. It should only:

• parse commands
• load merged config
• wire services
• print results

Do not hide business logic in the CLI layer.

2. Make Config Precedence Explicit

Use a predictable merge order:

1. defaults
2. user config
3. project config
4. local config
5. environment overrides

If a runtime value cannot be traced back to one of these sources, the harness is already drifting into opacity.

3. Gate Tools Before Execution

Define permission policy before the query loop runs tools.

Minimum pattern:

• default and plan expose read-only tools
• write or shell tools require a stronger mode
• bypassPermissions should be explicit and rare

Permission checks belong before tool execution, not after damage is already possible.

4. Start with a Tiny Tool Surface

Default tool set should be boring and legible:

• list_files
• read_file
• grep
• bash

Do not add tools because the upstream product has them. Add tools only when they expand capability without making the harness harder to reason about.

5. Keep Skills File-Backed

Discover skills from SKILL.md files with frontmatter metadata. Avoid hidden registration layers, magic imports, or remote skill switches.