Building a Claude Code Harness — Overview of Settings, Rules, and Skills

When you start using Claude Code across a team or multiple projects, problems arise: “Claude behaves differently depending on the project” and “every time a new member joins, rules have to be shared verbally.” The harness is the configuration system that solves these problems. In this section, you will learn systematically about the harness — from the concept through the actual build steps — broken into 11 topics.

---

What Is a Harness?

A harness refers to the entire configuration system that controls Claude Code behavior. Concretely, it consists of a three-layer structure: CLAUDE.md, the shared/ directory, and the .claude/ adapter layer.

Just as an automotive wire harness bundles multiple electrical wires and manages them neatly, Claude Code’s harness is a mechanism that bundles “rules,” “skills,” “commands,” and “permission settings” in one place. By introducing a harness, Claude Code functions not as a “general-purpose AI that tries to answer anything” but as “a project member who knows this project’s conventions.”

---

Why Is a Harness Necessary?

When using Claude Code across multiple contexts without a harness, the following problems arise.

• Lack of consistency: Even for the same task, it answers with different approaches or coding styles each session
• Volatile rules: Even if you convey “the rules for X” in one session, they are forgotten in the next
• Onboarding costs: Every time a new member starts using Claude Code, project-specific rules have to be communicated verbally
• Difficulty managing permissions: There is no centralized way to manage which commands are allowed and what is prohibited

The harness structurally solves these problems. By declaring rules as files, sharing them across the team, and versioning them, you can manage Claude Code’s behavior the same way you manage code.

---

Overview of the Three-Layer Structure

The harness consists of the following three layers.

project-root/
├── CLAUDE.md                 # Layer 1: Entry point
├── shared/                   # Layer 2: Shared assets (source of truth)
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   └── commands/
└── .claude/                  # Layer 3: Adapter layer (symlinks)
    ├── settings.json
    ├── skills/  → shared/skills/
    ├── agents/  → shared/agents/
    └── commands/ → shared/commands/

Layer 1 (CLAUDE.md) is the “startup contract” that Claude Code reads first. It holds non-negotiable rules, a command list, and references to the shared asset map. Instead of writing lengthy specifications directly, it references files in shared/.

Layer 2 (shared/) is the source of truth where the actual rules, skills, and commands are stored. It is collaboratively edited by the team and managed with Git.

Layer 3 (.claude/) is the configuration layer that Claude Code tools read. It exposes shared assets in a tool-specific format via symlinks to shared/. Permission settings (settings.json) are also placed here.

---

Details of Each Component

Component	Role	Example
CLAUDE.md	Entry point. Declares non-negotiable rules and references to shared/	Non-Negotiable Rules, Shared Asset Map
shared/rules/	Collection of safety and quality rule files. Referenced from CLAUDE.md	build-and-deploy.md, content-i18n.md
shared/skills/*/SKILL.md	Skill definitions loaded when Claude performs specific tasks	docs-content/SKILL.md, blog-content/SKILL.md
shared/agents/	Specs defining roles, constraints, and tool permissions for sub-agents	docs-content.md, blog-content.md
shared/commands/	Custom command definitions that users invoke with a slash	blog.md, docs.md
.claude/settings.json	Tool permissions, hooks, and MCP plugin settings	permissions, hooks
.claude/ adapter layer	The layer that bundles symlinks to shared/ with Claude Code-specific settings	.claude/skills/ → shared/skills/

---

Roadmap for This Section

In this section, you will explore each harness component in depth.

Topic	Content
CLAUDE.md Hierarchy Design	Three-layer design across global, project, and subdirectory levels and best practices
Settings JSON Design	How to configure permissions, hooks, and MCP
Rules File Design	How to declare safety and quality rules and naming conventions
Custom Commands Deep Dive	Design patterns for reusable commands
Skills Design Patterns	Task-specific skill definitions and how to choose among them
Agents Spec Design	How to define sub-agent roles, constraints, and tool restrictions. Learn the Commands / Skills / Agents triangle and how to write descriptions
Hooks Implementation	Implement automation, validation, and notifications using lifecycle hooks such as PreToolUse, PostToolUse, and Stop
MCP Plugins Integration	How to configure local and remote MCP servers and manage credentials securely
Memory System Design	Design guidelines for the 4 memory types (user, feedback, project, reference) and the MEMORY.md index
Harness Testing and Validation	How to verify that settings function as intended
Marketplace Publishing	How to share and distribute the harness you have created

---

Prerequisites

This section assumes the following knowledge.

• Level 3: Experience creating and using custom commands (.claude/commands/)
• Level 4: Understanding of the CLAUDE.md hierarchy (global, project, subdirectory)

If you have not yet covered Levels 3 and 4, first refer to Claude Code Level Up.

---

Hands-on Exercise: Verify This Project’s Harness

This project (ai_learning_playground) is itself an implementation example of a harness. Check the actual directory structure to see the three-layer structure with your own eyes.

Step 1: Check the Directory Structure

Navigate to the project root in your terminal and check the shared asset directory.

ls shared/

Example output:

agents    commands  rules     settings  skills    tools     workflow

ls shared/rules/

Example output:

build-and-deploy.md  content-i18n.md  folder-safety.md  no-ui-regression.md  security.md  spec-first.md

✅ Verify: If multiple .md files appear in shared/rules/, the rules layer is correctly in place.

Step 2: Check the Entry Point

cat CLAUDE.md

Confirm that the three sections ## Non-Negotiable Rules, ## Commands, and ## Shared Asset Map are present.

✅ Verify: If the ## Shared Asset Map section includes references to shared/rules/*.md and shared/skills/*/SKILL.md, the entry point is functioning correctly.

Step 3: Check the Adapter Layer

ls -la .claude/

Example output:

agents -> ../shared/agents
commands -> ../shared/commands
settings.json
skills -> (links to each skill file)
workflow -> ../shared/workflow

✅ Verify: If agents, commands, and workflow appear as symlinks (->), the adapter layer is correctly configured.

What is happening: The .claude/ directory references shared/ through symlinks. This allows Claude Code tools to read the .claude/ structure while the actual settings are centrally managed in shared/. Edits to shared/ are immediately reflected in .claude/.

---

Summary

• A harness is the Claude Code configuration system consisting of three layers: CLAUDE.md, shared/, and .claude/
• CLAUDE.md is the entry point Claude reads first, delegating lengthy specifications to shared/
• shared/ is the source of truth storing rules, skills, agents, and commands, managed with Git
• .claude/ is the adapter layer holding symlinks to shared/ and permission settings
• This project itself is a working implementation example of a harness that can be referenced

---

Next Steps

Start with CLAUDE.md Hierarchy Design to learn the design patterns for the entry point.

---

Frequently Asked Questions

Q: Is a harness necessary for personal use?

A: For a single project used by one person, CLAUDE.md alone is sufficient in many cases. The three-layer harness structure is especially effective when you want to share rules across multiple projects or when operating Claude Code as a team.

Q: Does the shared/ directory have to use this exact name?

A: The directory name is arbitrary. However, you need to explicitly state the path in the Shared Asset Map in CLAUDE.md. This project uses shared/, but you can choose a name that fits your team’s context, such as config/ or policies/.

Q: How do I create the symlinks in .claude/?

A: Create them with shell commands such as ln -s ../shared/agents .claude/agents. Details are covered in Hooks Implementation and Settings JSON Design.

Q: Are the rules written in CLAUDE.md always followed?

A: The rules in CLAUDE.md are read as context by Claude Code. There is no guarantee the model will always follow them. For important constraints (such as prohibiting production deployment), it is recommended to control them at the system level using the permissions field in .claude/settings.json.

See the references for the external specifications and background sources used on this page.[1][2]

References

1. Anthropic, Claude Code documentation
2. Anthropic, Claude API documentation