What Is Harness Engineering? A Three-Layer AI Development System
What you’ll learn
- Why conversation alone does not stabilize quality in continuous AI work
- How harness engineering integrates rules, work procedures, and verification
- How to adapt this site’s three-layer structure to place support systems in another project
Harness Engineering Integrates Rules, Procedures, and Verification
In this article, “harness engineering” means designing the harness: rules, work procedures, and verification methods that support AI work. On this site, repeated conversational context evolved into role-based management of shared rules, Skills (procedures and reference material for specific tasks), and automated checks. Separating official product capabilities from the site’s three-layer pattern helps determine which supporting systems another project actually needs.
By the end of this article, you will have practical criteria for answering “What does harness engineering design, and how is it separated from product features?” in your own context.
Design a Harness in Three Layers: Rules, Procedures, and Verification
Using AI to answer one-off questions is quite different from integrating it into an ongoing project. The challenges that surface are different too.
In ongoing projects, recurring situations can arise: an AI implements the same task differently in a new conversation, or a rule given in one conversation is not followed in the next.
The base model does not automatically and permanently retain the contents of a separate session. If product history, Memory, project settings, or external files are unavailable, earlier rules and decisions are not automatically carried into the next session. Claude Code officially documents a way to pass project context through memory files such as CLAUDE.md.[1]
In AI agent work, the broader idea of designing instructions, tools, permissions, environment, validation, and feedback together is sometimes described as an agent harness (a project system of rules, procedures, and validation) or Harness Engineering. In this article, I describe the specific three-layer structure I use for AI Learning Playground.
On this site, I use “Harness Engineering” to mean the combined system of rules, settings, validation, handoff notes, and review practices that help AI work at a consistent quality level. The scope of this term and the three-layer arrangement describe this site’s practice. They should not be treated as a vendor feature name or a shared three-layer specification.
The Harness Name Reflects Its Role in Constraining, Connecting, and Verifying AI Work
A harness is the equipment used to guide and control a horse, directing its energy toward the intended purpose. I use the same word here because the idea is similar: rather than treating AI as a simple question-and-answer tool, I design a system of settings, rules, and procedures that keeps AI moving in the right direction for the project.
The goal is not to change AI itself. It is to arrange what AI refers to so that its behavior stays consistent with the project’s intent across all sessions.
Separating Official Features from This Site’s Design
In this article, the official-feature side means Claude Code using CLAUDE.md as project memory, settings files managing permission and environment behavior, and Claude Code features such as Hooks (automatic actions that run at defined timings, such as before or after a command) and Skills (task-specific instruction and reference packages) being available.[1][2][3][4] Those are vendor-documented Claude Code capabilities.
By contrast, the term “Harness Engineering,” the decision to keep shared rules under shared/, and the three-layer structure that combines CLAUDE.md, shared/, and a lessons log are my way of explaining how this site is operated. They use official features, but Claude Code does not define this three-layer structure as an official pattern.
| Viewpoint | Status |
|---|---|
Using CLAUDE.md for project context | Based on Claude Code official documentation |
| Combining settings, permissions, Hooks, and Skills | Based on Claude Code official features |
Making shared/ the source of truth for common rules | AI Learning Playground-specific design |
| The scope of “Harness Engineering” in this article | A way to describe this site’s practice |
| Organizing the setup as three layers | This site’s operating pattern |
This Site Places Information in Three Layers: Entrypoint, Shared Rules, and Lessons
On this site, I combine those official features with my own project design and place information in three layers. The entrypoint directs the agent to shared rules and procedures, while past failures are recorded in the lessons log. Automated checks run as separate scripts and inspect some of the constraints written in these layers. Verification works across the layers rather than occupying only the third layer.
1. Project Configuration (CLAUDE.md)
This is the file AI reads first when starting work on the project. It contains the fundamental policies: what AI must not do, what the directory structure looks like, and which commands are permitted. Think of it as the orientation document handed to a new team member.
2. Rules and Skills (shared/ directory)
This is a collection of files covering procedures and constraints for specific types of work. Examples include how to write content, how to deploy, and how to conduct a review. Think of it as the operations manual. AI refers to the relevant file for each task.
3. Lessons Log (lessons.md)
This file records problems that occurred during AI sessions and how they were resolved. When product history or Memory cannot be relied on, the same problem can recur. Having AI read the lessons log provides context about past problems so they are less likely to repeat.
Defect Fixes Recorded in Lessons and Change History
Fixing Heading Links through Configuration and Checks
The lessons log records a broken link preview that overlapped the article when the pointer hovered over a heading. The September 5, 2026 entry explains that hiding the link with CSS leaves the element in place, so the setting that generates the link must change.
Markdown, mentioned in the log, is a text format that uses # at the start of a line for a heading and - for a list item. The Japanese article quotes the rule field from the actual shared/workflow/lessons.md entry. The following is its English translation. Setting and check names are retained because they are needed to reproduce the fix.
Rule: For Markdown headings in Docs, Blog, and About, preserve IDs and table-of-contents links while disabling Starlight hover permalink generation with
markdown.headingLinks: false.verify-ui-invariants.mjschecks this setting indev:check,harness:check, andprebuild, rejecting its removal, a change totrue, or placement outside the Starlight settings.
Mapped to the three layers, the entrypoint directs the agent to shared rules, shared rules establish constraints and checks for preserving the UI, and the lessons log preserves the symptom, reason, and applicable situations. Automated checks also detect removal of the setting, a change to true, or placement in the wrong location. Reading a record and mechanically blocking a violation serve different purposes.
The repository includes tests that reject these three kinds of configuration changes. This demonstrates an implemented check for recurrence conditions. It does not measure how often the check stopped a change in operation or how many reader-visible defects it prevented. No prevention count or reduction rate is available. The lessons.md article also explains how to use these records.
Using One Display Rule in the Interface and the Check
Another example is the saved change record 0ec777d8 from June 14, 2026. The condition for displaying learning information and the check for that condition were written separately. An outdated check rejected display behavior that matched the specification. The lessons log also records that generating publication files failed because of this mismatch.
The fix changed five files so the display and the check use one shared rule for deciding whether learning information appears. It also added checks for whether learning information should appear in five kinds of pages: the locale root, topic overview, section overview, article, and blog. The saved before-and-after code shows that the separate conditions were consolidated into one shared operation. It does not measure time saved on rework or subsequent prevented incidents.
Implementation Excerpts: One Display Condition and a Test for Invalid Settings
The current src/components/page-title-learning-info.mjs contains the implementation below. entryId identifies a page, with language and hierarchy expressed as a value such as ja/ai/security. A true value for showLearningInfo means that learning information appears. The rule excludes blog and profile pages and uses the learning-page hierarchy to decide where to display it.
export function getPageTitleLearningInfoState(entryId) {
const idSegments = entryId.split('/').filter(Boolean);
const isBlogPage = idSegments[1] === 'blog';
const isAboutPage = idSegments[1] === 'about';
const isSectionOrArticle = idSegments.length >= 3;
return {
lang: idSegments[0] === 'en' ? 'en' : 'ja',
showLearningInfo: isSectionOrArticle && !isBlogPage && !isAboutPage,
};
}The interface and the check import this function and use the same condition. The following five inputs and expected display states form the check. The October 13, 2026 check returned the expected value for all five.
| Input | Page type | Display learning information |
|---|---|---|
ja | Locale root | No |
en/ai | Topic overview | No |
ja/ai/security | Section overview | Yes |
en/ai/security/prompt-injection | Article | Yes |
ja/blog/example-post | Blog | No |
For heading links, a test deliberately restores an invalid setting to check whether the inspection detects the problem. This is an actual excerpt from scripts/verify-ui-invariants.test.mjs. assert.match checks whether the result includes the instruction to disable heading links.
test('rejects re-enabling Starlight heading hover links', () => {
const source = `
starlight({
title: 'AI Learning Playground',
markdown: {
headingLinks: true,
},
plugins: [],
})
`;
assert.match(getUiInvariantViolations(source).join('\n'), /headingLinks to false/);
});The command is node --test scripts/verify-ui-invariants.test.mjs. All eight tests passed on October 13, 2026, including three tests that reject deleting the setting, changing it to true, and putting it in the wrong location. This confirms that the checks work under those specified conditions. It does not measure incidents prevented in production or AI model performance. Commit history alone cannot establish whether I wrote each line or AI generated it.
Harness Design Can Start from Business Rules and Review Steps
Business rules and procedures can be organized in Markdown text files. Programming knowledge is not required to start organizing rules. Automated checks, however, require scripts and tests. If you can describe the rules you want AI to follow, the things it must not do, and the steps you want it to take, you can design a harness.
Without this design in place, each new conversation requires re-explaining the same rules, and AI’s decisions vary from one session to the next.
Summary: Separate Official Capabilities from the Three-Layer Pattern and Add Only What You Need
Harness Engineering surrounds ongoing AI work with rules, work procedures, and verification. Separating official capabilities such as CLAUDE.md, settings, Hooks, and Skills from this site’s shared/ source-of-truth and three-layer pattern clarifies what the product provides and what the project must design.
The first decision is where to place one premise repeatedly explained to AI: in a rule, a procedure, or a verification check. The three-layer structure is a reusable project pattern, not an official architecture shared by every product.
References
- Anthropic, How Claude remembers your project, Claude Code Docs
- Anthropic, Claude Code settings, Claude Code Docs
- Anthropic, Hooks reference, Claude Code Docs
- Anthropic, Extend Claude with skills, Claude Code Docs
For the latest releases and updates, check the official website and official documentation.