Tessl Coding Agent Guardrails Turn Repository Files Into a Control Layer

Tessl has published a four-part framework for controlling coding agents through files that teams own, despite growing dependence on hosted models. The Tessl coding agent guardrails separate persistent instructions, path-specific rules, reusable capabilities, and automatic hooks. That distinction matters because a written request and an enforced restriction do not provide the same protection.

The framework uses CLAUDE.md, .claude/rules/, capability files under .claude/, and hooks connected through Claude Code configuration. Each layer handles a different point in an agent’s workflow. Together, they move operational knowledge from temporary conversations into versioned repository assets.

The central conflict is not Tessl versus another developer tool. It is advisory context versus deterministic enforcement. A model can misunderstand or overlook prose, while a hook can reject an action before it runs. Teams now need to decide which expectations belong in prompts and which require executable controls.

Tessl Coding Agent Guardrails Divide One Prompt Into Four Layers

Tessl’s key move is separating guidance by when it loads, what it controls, and whether the agent can ignore it.

The four-file framework starts with CLAUDE.md. This repository file gives Claude Code persistent project context. Suitable material includes build commands, architectural boundaries, directory conventions, and testing expectations.

That layer should describe facts the agent needs across many tasks. It can explain that a service uses a specific package manager or that database migrations are append-only. It can also identify the commands that establish whether a change works.

The second layer places focused rules in .claude/rules/. A rule can include path patterns that determine when its instructions enter the active context. An API validation policy can appear only when the agent touches API handlers, for example.

Path scoping addresses a practical problem with large instruction files. An agent working on documentation does not need every backend convention in its context. Loading irrelevant material consumes tokens and competes with instructions that matter for the current task.

The third layer stores reusable capabilities under .claude/. Skills are folders containing a SKILL.md file, instructions, scripts, and supporting resources. They package a procedure that the agent or developer can invoke when relevant.

A release checklist illustrates the difference. The repository overview can state how releases work, but the complete sequence belongs in a release skill. That keeps the longer procedure out of ordinary coding sessions.

The fourth layer uses hooks for actions that should fire at defined lifecycle events. Hooks can inspect proposed tool calls, run formatters after edits, or stop dangerous commands. Their configuration normally lives in settings or related project files.

This separation changes the meaning of “agent instructions.” The files no longer form one large prompt that asks the model to remember everything. They become distinct controls with different loading and enforcement behavior.

Anthropic’s own steering guidance supports this allocation. It distinguishes always-loaded context, path-scoped rules, on-demand procedures, isolated subagents, and lifecycle automation.

Tessl narrows that broader menu into a repository ownership argument. The model provider still operates the model and agent runtime. The development team owns the files that describe how the agent should behave inside its codebase.

That ownership makes the control layer inspectable. A team can review changes through pull requests, compare versions, assign maintainers, and revert a harmful rule. Chat history rarely offers the same operational clarity.

The files can also travel with the project. A new contributor receives the shared conventions when cloning the repository. A fresh agent session can recover the same instructions without relying on someone’s earlier conversation.

The framework does not eliminate model uncertainty. It organizes uncertainty into layers that teams can test independently. That is the more important change.

The Pressure Falls on Teams Treating CLAUDE.md as a Policy Engine

A long instruction file can guide an agent, but it cannot reliably function as an access-control system.

Many teams begin with one CLAUDE.md because it produces immediate improvements. The agent stops guessing common commands, follows established naming patterns, and gains a basic map of the repository. Those benefits make the file easy to overextend.

The problem appears when every exception becomes another paragraph. Security requirements, release procedures, frontend conventions, database restrictions, and personal preferences accumulate in the same document. Every session then pays the context cost.

Anthropic recommends treating the root file as an overview or index. Its current guidance suggests keeping CLAUDE.md under 200 lines, assigning an owner, and reviewing changes like code. That recommendation reflects an attention problem, not merely a formatting preference.

Every always-loaded instruction competes with source files, task details, tool output, and recent conversation. More guidance does not guarantee stronger compliance. A crowded prompt can make the relevant requirement harder to identify.

Nested instruction files help localize some knowledge. According to the official project memory documentation, files below the working directory can load when Claude accesses that part of the tree. This supports team-specific conventions inside a monorepo.

Path-scoped rules offer a more direct option for cross-cutting concerns. A rule can target several file patterns without duplicating instructions in multiple directories. It can cover all migration files or every API handler across separate packages.

The distinction pressures engineering leaders to classify their requirements. A coding convention belongs in context because judgment remains useful. A repeatable workflow belongs in a skill because it needs ordered steps. A prohibited command needs a stronger barrier.

Without that classification, CLAUDE.md becomes an informal policy database. Developers may assume that writing “never modify production configuration” creates a reliable boundary. It does not.

An agent interprets prose within a changing context. Long sessions, ambiguous instructions, conflicting files, and prompt injection can weaken adherence. Even a capable model can make the wrong judgment under those conditions.

This limitation also affects audits. A reviewer can confirm that a sentence exists, but cannot infer its real enforcement rate. The rule may load correctly and still lose against a more immediate instruction.

Teams adopting autonomous or unattended workflows face the greatest pressure. A missed convention during supervised coding creates review work. A missed safety restriction during unattended execution can alter files, expose data, or invoke an unwanted command.

The framework therefore asks teams to stop measuring governance by document size. The better question is whether each requirement reaches the agent at the right moment with sufficient authority.

That question extends beyond Claude Code. Other coding agents support repository instruction files, reusable workflows, or event-based controls under different names. The specific paths vary, but the design problem remains consistent.

A repository needs concise context, selective procedures, narrow permissions, and enforceable boundaries. Combining those functions in one prompt hides their differences.

Advisory Instructions and Deterministic Hooks Are Not Equivalent

The decisive boundary is whether the model chooses to comply or the runtime blocks noncompliance.

A CLAUDE.md statement influences the model’s next decision. A rule file does the same with better targeting. A skill provides a reusable procedure, but the agent still interprets and executes that procedure.

Hooks operate at another layer. Claude Code triggers them when defined events occur, such as a tool request, file edit, session start, or attempted completion. The runtime initiates the hook rather than waiting for the model to remember it.

A PreToolUse hook can inspect a proposed command before execution. If the command violates a policy, a command hook can return a blocking result. The agent then receives the reason and must choose another path.

The official hooks guide describes several handler types. Command handlers execute scripts, while prompt and agent handlers use model judgment. This distinction matters because not every hook is fully deterministic.

A hook that always launches is deterministic at the trigger level. Its decision may still be probabilistic if an LLM evaluates the request. Teams should reserve command-based checks for conditions that software can evaluate directly.

Consider a repository that prohibits changes to generated files. A prose instruction tells the agent to avoid them. A path rule repeats that expectation when relevant files appear. A hook can inspect the write target and reject the operation.

Those layers can work together. The instruction explains the repository’s design, while the hook prevents a known failure mode. The agent receives both context and an enforceable boundary.

The same pattern applies to commands. A team can describe its deployment process in a skill, then block direct production commands through permissions or hooks. The skill provides the approved route, while the control prevents shortcuts.

Post-edit hooks serve a different purpose. They can run formatting, linting, or focused validation after an agent changes a file. That automation reduces reliance on the agent remembering another checklist item.

Completion hooks can test whether required checks passed before the agent stops. However, they need protection against loops. A failing stop hook that repeatedly asks the agent to continue can consume time without improving the result.

Hooks also introduce executable code into the control plane. A flawed script can block legitimate work, leak information, or add latency to every matching event. Teams must review hook changes with the same care as build and deployment automation.

Ownership does not automatically create safety. A malicious repository can contain configuration that requests dangerous behavior. Developers still need workspace trust, restrictive permissions, code review, and isolated execution for unfamiliar projects.

The phrase “files you own” therefore has two meanings. It describes portability and governance, but it also assigns responsibility. The team must maintain those files, test their effects, and protect them from unauthorized modification.

This is why permissions remain important. Anthropic’s permission controls support allow and deny rules for tools and commands. Deny rules take precedence over matching allow rules.

Hooks can evaluate richer conditions, while permissions provide a more direct access boundary. Neither should become a substitute for operating-system isolation when the consequences are serious.

Containers, restricted credentials, branch protections, and read-only mounts remain stronger controls. Repository files sit inside that larger defense system. They should reduce risk without pretending to replace infrastructure security.

The main takeaway is simple. If a requirement says “prefer,” it can remain guidance. If it says “must never,” the team should look for an enforceable control.

Skills Turn Repeated Agent Work Into Reviewable Repository Assets

Skills matter because they convert temporary prompting habits into procedures that teams can inspect, test, and reuse.

A developer often discovers a useful agent workflow through trial and error. The final prompt may include diagnostic commands, decision criteria, formatting requirements, and verification steps. Without a shared file, that knowledge disappears inside one conversation.

A skill preserves the workflow in a named directory. Its SKILL.md contains metadata and instructions, while adjacent scripts or references support the procedure. The repository can version the complete package.

Claude Code loads only a skill’s name and description initially. The full body enters context when the skill becomes relevant or someone invokes it. Official skill documentation positions this behavior as an alternative to placing long procedures in CLAUDE.md.

That loading model creates an economic advantage. Detailed release, migration, review, and incident procedures can remain available without burdening every session. Context becomes conditional instead of permanent.

It also improves discoverability. A new engineer can inspect the skills directory and see which workflows the team has formalized. The files reveal what the organization expects from both humans and agents.

Reviewability is equally important. A changed prompt inside chat is difficult to audit. A changed skill produces a diff. Reviewers can identify a removed safety check or an added command before it reaches routine use.

Skills can include scripts for deterministic subtasks. A migration skill might call a repository-owned validator rather than asking the model to reproduce validation logic. The agent handles judgment, while code handles repeatable computation.

However, a skill is still primarily a procedure. Its presence does not prove that the agent will invoke it at the right moment. Descriptions must clearly state when the skill applies, and teams need tests that exercise triggering behavior.

Manual invocation can reduce ambiguity for sensitive operations. A developer can explicitly request a release review rather than depending on automatic matching. The skill then supplies the consistent workflow.

Capabilities also create maintenance obligations. Procedures become stale when command names, architectures, or deployment systems change. A reliable skill needs an owner, examples, and a review cycle.

Teams should watch for duplicated authority. If the same requirement appears in CLAUDE.md, three rules, and two skills, later edits can create contradictions. The agent then receives multiple versions of the supposed truth.

A better arrangement gives each fact one primary home. The root file can point to a capability without copying its complete body. Path rules can add local constraints, while skills own multi-step procedures.

This resembles ordinary software design. Small modules with clear responsibilities remain easier to change than one global configuration object. The agent control layer benefits from the same separation.

The approach can also preserve organizational knowledge. Build recovery, dependency upgrades, and security review often depend on a few experienced engineers. Encoding those workflows makes the knowledge available during future sessions.

That connection is especially relevant when technical evidence is scattered across documents. A searchable engineering knowledge base can support the source material, while skills define how agents use it.

The two systems solve different problems. Knowledge storage preserves facts and decisions. Skills turn selected knowledge into an operational procedure.

The practical advantage is not that the agent suddenly becomes infallible. The advantage is that the team can inspect the procedure it expects the agent to follow.

File Ownership Does Not Remove the Security Gap

Repository-controlled guardrails improve accountability, but they remain vulnerable to conflicts, tampering, and incomplete enforcement.

The first uncertainty concerns instruction precedence. A project can contain root guidance, nested guidance, path rules, skill instructions, user preferences, and managed organization settings. Those layers can disagree.

A team may believe that its repository expresses one policy when a developer’s personal configuration changes the behavior. The opposite problem can also occur. Central policy may prevent a local workflow that the repository expects.

Configuration visibility is therefore essential. Developers need a way to see which files loaded, which rules matched, and which permissions affected a decision. Otherwise, failures appear random.

The second uncertainty concerns mutability. If an agent can edit the files that constrain it, the control plane shares the same trust boundary as ordinary code. A task might accidentally weaken a rule while changing nearby configuration.

Critical controls should receive stronger protection. Code ownership, required reviews, protected branches, and read-only execution environments can make unauthorized changes harder. Sensitive hooks should not depend on agent goodwill.

The third uncertainty is portability. CLAUDE.md has broad recognition, but directories for rules, skills, agents, and hooks remain tool-specific. A repository that supports several coding agents can accumulate parallel configurations.

Tessl has an interest in reducing that fragmentation because its product manages reusable agent context and specifications. Its framework therefore reflects both a general design pattern and a particular tool environment.

Teams should separate those two claims. The layered model is useful across coding agents. Exact file paths and loading behavior must still be verified against each runtime.

The fourth uncertainty concerns false confidence. A hook can block a known command pattern but miss an equivalent action. A deny rule for one shell command does not necessarily cover a script, package task, or external tool that produces the same effect.

Controls need adversarial testing. Teams should attempt prohibited operations through alternative syntax, indirect scripts, and different tools. A guardrail that passes only its original example remains fragile.

Legitimate work also needs testing. A broad block can prevent harmless commands or interrupt common workflows. Developers may then request exceptions, bypass the control, or disable it entirely.

Latency creates another tradeoff. A formatter after every edit may be acceptable, while a full test suite after every file change can make the agent unusable. Controls should match the cost and consequence of the event.

Fast checks belong close to each edit. Larger validation can run before commits or completion. Expensive security analysis may fit a dedicated skill, continuous integration job, or isolated review agent.

Prompt injection remains a serious concern. An agent can read untrusted issue text, documentation, generated artifacts, or dependency content. Malicious instructions inside those inputs may conflict with repository guidance.

Deterministic permissions and isolated execution reduce the possible damage. Prompt instructions alone cannot establish a security boundary because the same model interprets both trusted and untrusted text.

The safest reading of Tessl’s proposal is therefore narrower than its headline. Files can create a maintainable control layer. They cannot guarantee safe autonomy by themselves.

Three Signals Will Show Whether the Framework Holds Up

The next test is whether teams can measure adherence, portability, and enforcement instead of merely accumulating configuration files.

The first signal is better evaluation tooling for repository instructions. Teams need repeatable tasks that reveal whether an agent followed a rule, invoked the correct skill, and respected a boundary.

A useful evaluation should start from a clean environment. It should present the same task across multiple runs, record loaded configuration, and compare the resulting actions. That would expose probabilistic failures hidden by one successful demonstration.

If evaluation becomes routine, Tessl’s ownership argument grows stronger. Repository files would behave more like testable software assets. If teams cannot measure outcomes, the framework risks becoming prompt documentation with uncertain effects.

The second signal is convergence around portable capability formats. Skills already resemble a cross-tool packaging standard because they combine metadata, instructions, and supporting files. Rules and hooks remain less consistent.

Portability would reduce duplicate maintenance across Claude Code, Codex, Cursor, and other agents. It would also let organizations review one control definition instead of reconciling several near-copies.

However, superficial portability is not enough. A shared file format must preserve triggering, permissions, path matching, and enforcement semantics. Identical Markdown does not guarantee identical behavior.

If agent vendors publish precise loading and precedence rules, the framework becomes easier to trust. If each runtime silently interprets the same files differently, repository ownership will not solve operational ambiguity.

The third signal is stronger separation between guidance and hard policy. Anthropic already distinguishes model-facing instructions from hooks, permissions, managed settings, and system isolation. Teams now need tools that make this distinction visible.

A policy interface should identify which controls are advisory, which always trigger, and which actually block actions. Audit logs should show why a command was allowed or denied.

This signal will strengthen the framework if developers can trace every important restriction to an enforceable layer. It will weaken the framework if sensitive policies remain buried inside prose.

The immediate action for engineering teams is not to create all four layers at once. They should inventory their existing instructions and classify each statement by function.

Project facts and common commands belong in concise persistent context. File-specific conventions belong in scoped rules. Repeated procedures belong in skills. Prohibited actions belong in permissions, hooks, or stronger system controls.

That classification provides a practical test for Tessl coding agent guardrails. Can another engineer inspect the repository and explain what guides the agent, what activates on demand, and what cannot be bypassed?

If the answer is unclear, the repository does not yet have a control layer. It has a collection of prompts. The distinction will determine whether coding agents become dependable collaborators or simply faster sources of review work.