Deploying Claude Code for Non-Engineers: CLAUDE.md and Permission Pitfalls

The HUMAN_INPUT marker mentioned in this article is a placeholder left by the AI writing skill to indicate where a human should later fill in a specific value (e.g., <!-- HUMAN_INPUT: Fill in numerical value -->).

This article organizes design patterns for tech leads, senior engineers, and architects to safely deploy Claude Code for non-engineers. Management decisions (what to delegate, investment decisions, measuring ROI) are left to the sister pillar, Organizational Design for Non-Engineers Using Claude Code. Here, we deal with the technical guarantees at the level tech leads can design and implement.

Claude Code deployment for non-engineers can be technically guaranteed through three axes:

1. 3-Layer Scoping of CLAUDE.md: Separating responsibility boundaries across global, project, and directory levels.
2. Skill I/O Constraints: Declaring inputs, outputs, and forbidden operations to mechanically prevent scope creep.
3. 3-Layer Permission Model: Creating a safety net for file operations with read-only zones, write guards, and bash prohibitions.

I will first show what happens if you hand Claude Code to a non-engineer without these three axes in place.

3 Key Takeaways:

1. CLAUDE.md is not just about “writing something” but essentially about the design of responsibilities—what to write at which layer. Mixing global, project, and directory layers leads to conflicting constraints and confuses non-engineers.
2. Skill I/O contracts (declarations of inputs, outputs, and forbidden operations) are mechanical shut-off devices for scope creep. Without them, LLMs will execute outside the intended range based on context, thinking they are being helpful.
3. Permission model errors occur silently. Merely “instructing not to touch certain things” without setting read-only zones means non-engineers will continue to use Claude Code without understanding its operational range.

Why Design Claude Code Deployment for Non-Engineers: Yakumo’s Dogfooding Context

Real-world Examples of Non-Engineers Using Claude Code

At Yakumo, the primary user of Claude Code is the representative (PM and business lead), who is not an engineer. Specifically, Claude Code is operational in the following tasks:

• Corporate Site Operations: Updating articles and adjusting designs for a site built with Astro, React, and Tailwind. A person who can read and write HTML/CSS but requires external engineer review for architectural design operates this daily.
• Skill Operations for Synapse (Cross-functional Agent Organization): The PM directly invokes skills defined in .claude/skills/ for creating proposals, generating meeting minutes, and weekly reports.
• Article Pipeline (mcluhan engine) Operations: Operating the entire flow where agents generate articles from brief YAMLs via Claude Code, without writing code.

Specifically, the representative (PM and business lead) has been using Claude Code daily since July 2025. Article updates on the corporate site, synapse skill invocations, and mcluhan article pipeline operations—all are handled through Claude Code as a “business interface” without directly writing code.

These are possible not because we are simply “letting them use Claude Code,” but as a result of a tech lead designing an environment that can be handed over to Claude Code. Without design, scope deviations occur the moment a non-engineer operates Claude Code.

What Happens Without Tech Lead Design

If you hand Claude Code to a non-engineer without a design, the following three types of problems will occur in sequence:

Stage 1: Scope Deviation (Within the first few days) Claude Code is an agent that completes implementation once an intent is communicated. When a non-engineer instructs it to “fix the layout of this page,” Claude Code rewrites CSS files, components, and sometimes configuration files it deems relevant. “Files I didn’t want touched directly have changed” is the symptom of the first stage.

Stage 2: Silent Progression of Accidents (Within a few weeks) Even if scope deviations recur, a non-engineer cannot judge which files have changed. Since they don’t understand the meaning of a Git diff, changes accumulate in a state that “seems to be working.”

Stage 3: Explosion of Impact Range (A few weeks to months later) The impact of the accumulated changes becomes manifest in production. Identifying the cause becomes difficult, and fixing it takes several times the usual effort.

At Yakumo, we experienced this cycle during the initial construction phase of synapse. We started with the idea that “constraints can be added later,” and as a result of granting too many permissions, the agent rewrote configuration files and affected other tasks. Specifically, the agent deleted Chrome settings (tab groups, pinned tabs) on its own, resetting the daily work environment once. Since we had already built a system-developer agent on Claude Code, it took about 3 days from identifying the cause to restoring settings and adding scope constraints to CLAUDE.md, but without system-developer, this accident would have lasted longer.

This experience is the starting point for the 3-axis design.

Responsibility Separation in CLAUDE.md: 3-Layer Scoping (Global / Project / Directory)

Global CLAUDE.md: Rules to Follow Across All Projects

~/.claude/CLAUDE.md (on macOS) applies to all projects operated by the user. Constraints written here are always active regardless of the project.

What to Write in Global:

# Common User Settings

## Forbidden Hardcoding (Common to all projects)
- No magic numbers: Reference colors, font sizes, and spacing from config files.
- No direct font specification: Do not call loadFont in individual components.

## Commit Conventions
- Commit messages must be in English.
- 1 commit = 1 logical unit.

What NOT to Write in Global:

• Project-specific directory or file names.
• Prohibited operations for a specific project (e.g., forbidding direct editing of src/content/magazine).
• Business domain-specific rules (e.g., “Save proposals to Google Drive”).

Writing project-specific rules in global unintentionally restricts operations in other projects. Non-engineers will be confused as to why “it worked in another project but doesn’t work here.”

Project CLAUDE.md: Project-Specific Constraints

The CLAUDE.md placed at the project root applies to all operations within that project. This is the most important layer for a tech lead to prepare before a non-engineer starts operating.

What to Write in Project:

# Corporate Site

## Reference Documents (Read before deciding)
| Reference | Content |
|---|---|
| `src/_docs/ARCHITECTURE.md` | SSOT map, list of forbidden hardcoding |
| `src/_docs/DESIGN.md` | Visual language (colors, typography, spacing) |

## Invariant Conventions
- Git: Commit messages in English. Work on the `develop` branch (no direct pushes to main).
- Forbidden Hardcoding: Values must be placed in SSOT before referencing.
- Read the `_README.md` of the corresponding directory before editing under `src/`.

## Delegation of Implementation
- Structural editing of code, config, and YAML/JSON should generally be delegated to `web-developer` / `system-developer`.

3 Elements to Always Define in Project:

1. Explicit References: Which documents to read before working.
2. Invariant Conventions: Constraints where violation immediately becomes a problem (Git branches, forbidden hardcoding).
3. Delegation Rules: What is delegated to whom (explicitly stating operations non-engineers should not perform directly).

Directory _README.md: Scope Restrictions per Directory

Instructions in CLAUDE.md can only express “project-wide constraints.” To narrow the scope per directory, place a _README.md in each directory.

In Yakumo’s corporate-site, we define the following in src/content/magazine/_README.md:

# Magazine Content

Articles are placed in the path `{cluster}/{category}/{slug}.md`.
File name convention: `{YYYY-MM}-{kebab-case-slug}.md`

## Operational Permissibility
- Changing the slug frontmatter field is forbidden (directly linked to URL).
- Cluster and category must match the physical path and frontmatter.
- Articles with draft: true can be edited directly. For draft: false, go through blog-gate.

Claude Code reads this _README.md before operating on files under src/content/magazine/. When a non-engineer instructs it to “add an article,” the agent places the article at the path following the _README.md conventions in the appropriate format.

Priority and Conflict Resolution Rules for the 3 Layers

The priority of the three layers is directory _README.md > project CLAUDE.md > global CLAUDE.md. More specific constraints take precedence.

Typical conflict patterns:

Design Principle: A lower layer (directory) can override an upper layer (global/project), but contradictions operate without being recognized as errors. Tech leads need to periodically review for contradictions among the three layers.

An example at Yakumo is the Opus overreach on 2026-05-18. An exception clause in global CLAUDE.md and a delegation rule in project CLAUDE.md conflicted, leading to the main thread Opus directly executing a YAML structural retrofit (recorded in blog-ops/retros/2026-05-18-opus-mechanical-edit-overreach.md).

Skill I/O Scoping: Mechanically Preventing Scope Creep

Writing I/O Contracts: Declaring Inputs, Outputs, and Forbidden Operations in SKILL.md

A skill (.claude/skills/{skill-name}/SKILL.md) is a “definition file for work procedures,” but without an I/O contract, the LLM’s discretionary execution begins. An I/O contract consists of the following three elements:

# I/O Contract Section of SKILL.md

## Input
- `slug`: Article identifier (string)
- `brief`: Path to `blog-ops/articles/{slug}.yaml`

## Output
- `draft_md`: `blog-ops/output/rewrite/{slug}/draft_v{n}.md`
- Only update the `current_version` field in `_state.json`

## Scope Restrictions (Forbidden Operations)
- No direct writing under `src/content/magazine/` (Output only to `blog-ops/output/`)
- No Git commits or pushes.
- No writing to files other than the target slug.

The presence of this I/O contract in SKILL.md causes Claude Code to restrict the operational range of the skill within declared boundaries. When a non-engineer calls the skill, the LLM operates under the interpretation that “I cannot touch files not written in the I/O contract.”

As an operational insight, for skills that explicitly state I/O contracts in SKILL.md (e.g., blog-tech-write, blog-case-write, blog-review), “writing to locations not written in the contract” has not been observed since operations began. However, a logging infrastructure to mechanically count violation attempts is not yet in place, so we don’t have quantitative data like “X% compliance rate.” In the next phase, we plan to incorporate a mechanism to automatically aggregate violation attempts from gate logs and promote the fact that “I/O contracts are working” to an observable metric.

3 Principles of I/O Contract Design:

1. Declare outputs with specific paths: Instead of abstract paths like output/, specify them like blog-ops/output/rewrite/{slug}/draft_v{n}.md.
2. Write forbidden operations by “where not to write” rather than “what not to do”: Communicate the range accurately.
3. Explicitly forbid Git operations: If not instructed, the LLM might decide to “just go ahead and commit.”

3 Scope Creep Patterns and How to Block Them

Here we organize frequent patterns of scope creep that tech leads should be aware of.

Pattern A: Chain Writing to Related Files

Symptom: An instruction to “fix file A” leads to related files B and C also being “improved.”

Cause: No output destination is declared in the I/O contract, and the LLM judges from context to update things that “seem related.”

Blocking Method: Clearly state “No writing to files other than the target” in ## Scope Restrictions.

Pattern B: Automatic Execution of Git Operations

Symptom: After a skill execution, commits and pushes are performed automatically.

Cause: Forbidding Git operations is not written in the I/O contract, and it’s executed based on the LLM’s judgment that “saving changes is obvious.”

Blocking Method: Clearly state “No commits or pushes” in ## Scope Restrictions. Additionally, write “Commits only when explicitly instructed” in project CLAUDE.md.

Pattern C: Automatic Updating of Dependent Files

Symptom: A skill that changes a config also rewrites components referencing that config to “make them consistent.”

Cause: The LLM executes the ripple effect of changes as a “complementary action.”

Blocking Method: Clearly state “No rewriting of referencing components” in ## Scope Restrictions. If dependent changes are needed, separate them as another skill and manage them with an independent I/O contract.

Design of Declaring Skill Invocation Scopes in CLAUDE.md

Sometimes a skill’s I/O contract alone is insufficient. We add a design to declare “how to use this skill in this scope” from the CLAUDE.md side.

# Skill Scope Declaration Section of Project CLAUDE.md

## Usage Scope of Skills
- Call `blog-tech-write` only when a valid brief exists in `blog-ops/articles/`.
- `web-developer` is only responsible for implementation under `src/` (No Git operations or config changes allowed).
- `system-developer` is only responsible for editing `scripts/` and `blog-ops/config/`.

With this declaration, when a non-engineer instructs to “call blog-tech-write,” the constraints on the CLAUDE.md side are applied first. Even if a skill tries to start without a brief, the CLAUDE.md constraint stops it.

Permission Model Design: Read-only Zones / Write Guards / Bash Prohibitions

Read-only Zone Design: Permitting Reading while Forbidding Writing

Use the denyList in Claude Code’s permission settings (.claude/settings.json) to forbid writing to specific files and directories.

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(src/content/magazine/**)",
      "Write(blog-ops/output/**)"
    ],
    "deny": [
      "Write(src/_docs/**)",
      "Write(.claude/**)",
      "Write(src/config/**)",
      "Write(package.json)",
      "Write(tsconfig.json)"
    ]
  }
}

Files and Directories to Set as Read-only Zones:

When a non-engineer instructs to “change the color definitions in DESIGN.md,” Claude Code will respond with “Writing to this file is not permitted” if a read-only zone is set. Without settings, visual language definitions might be rewritten unintentionally.

Write Guard Design: Minimizing Writable Range

The opposite concept of a read-only zone is a write guard. This is an allowList approach of “you can only write here” to minimize the writable range.

Consider the write guard design policy in the following two stages:

Stage 1: Define Writable Ranges per Role

Divide writable ranges for each role operated by non-engineers (web-developer, system-developer).

# Correspondence Between Delegation Rules and Write Guards in CLAUDE.md

| Role | Writable Range |
|---|---|
| `web-developer` | `src/components/`, `src/pages/`, `src/content/` |
| `system-developer` | `scripts/`, `blog-ops/config/`, `blog-ops/output/` |
| Direct Non-engineer Operation | `src/content/magazine/**/*.md` (Article body only) |

Stage 2: Change Writable Range with Project Progress

Start with minimum write permissions initially and gradually expand based on track record. “Making everything writable and narrowing it later” does not work. Humans will leave it as is because “changing settings is a hassle.” The principle is to start with the least privilege.

At Yakumo, we have gradually added permission allow entries to .claude/settings.local.json. You can see the specific timing and flow of judgment in the git history of settings.local.json (git log --follow .claude/settings.local.json) for both the corporate-site and synapse repositories.

Bash Prohibition Design: Preventing Bash Execution for Non-Engineers

Executing bash commands is a high risk for non-engineers. Design flaws that “unintentionally let them execute” things like rm -rf, git push --force, or direct database operations should be prevented by the permission model.

// Bash Prohibition Settings in .claude/settings.json
{
  "permissions": {
    "deny": [
      "Bash(git push*)",
      "Bash(git commit --amend*)",
      "Bash(rm -rf*)",
      "Bash(git reset --hard*)",
      "Bash(git checkout --*)"
    ]
  }
}

3 Categories of Bash Prohibitions:

Alternative Pattern: Instead of giving bash directly, define permitted operations as skills. Enclose the operation “add, commit, and push in sequence” in a skill, and declare “push is forbidden” in the I/O contract. By going through a skill rather than bash, the forbidden operation gate will work.

3 Accident Prevention Patterns: From Real Examples at Yakumo

Pattern 1: Scope Deviation Due to Lack of CLAUDE.md Preparation

Situation: During the initial construction of synapse, a non-engineer requested work when no write guards or scope restrictions were written in CLAUDE.md.

What Happened: The agent, instructed to “improve the proposal skill,” judged to “make consistent” not only the skill file but also related config files and dependencies with other skills, rewriting multiple files. The requested change was correct, but the rippled changes affected other tasks.

Structure of the Cause: There was no constraint in CLAUDE.md to “not change files other than the target.” The LLM executed “maintaining consistency” as a reasonable judgment.

Design Solution: Added the following to project CLAUDE.md:

## Delegation Scope for Implementation
- Do not change files other than those requested.
- Prohibit additional changes just because they are "related."
- For changes affecting multiple files, list the impact range in advance and get user confirmation.

At the time, we did not systematically record the number of affected files or recovery time, but since adding scope constraints like “do not change files other than those requested” to CLAUDE.md, the same pattern (ripple effect from automatic editing of related files) has not been observed. This is the first case where “prevention by design” was visualized.

Pattern 2: File Destruction Due to Excessive Permission Granting

Situation: During development, we emptied the denyList in settings.json with the reasoning that “it’s easier to work if Read/Write permissions are granted to all files.”

What Happened: A non-engineer gave an ambiguous instruction to “organize the site settings.” The agent rewrote the forbidden vocabulary array in src/config/brand.ts (SSOT for brand settings) with the judgment of “deleting things that look old.” It wasn’t noticed immediately, and subsequent blog-gates started passing forbidden vocabulary checks that should have been NG (expressions that should have been NG were passing), which was discovered after multiple articles were published.

Structure of the Cause: There was no write guard, and the LLM misunderstood the purpose of the file in response to the ambiguous instruction “organize.” Having write permissions for the SSOT file allowed changes that the designer did not intend.

Design Solution: Set src/config/ as a read-only zone. Clearly stated in CLAUDE.md that changes to configuration files must be made directly by the tech lead, excluding them from non-engineer operations.

This was discovered during a blog-audit on the morning of 2026-05-18. Simultaneous publication of 48 articles for magazine-reset-timeline confirmed 4 HUMAN_INPUT leaks and 76 dead internal links, leading to the withdrawal of the articles on the same day (commit 086bb9b7).

Pattern 3: Unrestricted LLM Execution Due to Undefined Skills

Situation: The task of “creating a weekly report” was instructed directly to Claude Code without being defined as a skill.

What Happened: The first few times, the report was output in the intended format. However, because the LLM autonomously judged “which file to get information from” and “which format to output in” each time, the output was inconsistent. Sometimes it tried to save directly to Google Drive (external API operation occurred), and other times it opened files with customer data that it should not have referenced to get information (unintended file access).

Structure of the Cause: Because there was no I/O contract, the LLM autonomously chose the input, output, and operational means toward the goal of “creating a weekly report.” The goal was correct, but the means varied each time and could not be controlled.

Design Solution: Defined a weekly-report skill and wrote the following in the I/O contract:

## Input
- Reference file: `data/weekly-metrics.json` (This file only)

## Output
- `reports/weekly/{YYYY-MM-DD}.md` (This path only)

## Scope Restrictions
- Forbid external API calls (No direct operations on Google Drive/Sheets).
- No access to files in `data/` other than `weekly-metrics.json`.

Skill definitions are centralized under .claude/skills/. Major ones include .claude/skills/blog-tech-write/SKILL.md, .claude/skills/blog-review/SKILL.md, .claude/skills/blog-plan/SKILL.md, .claude/skills/blog-fact-check/SKILL.md, and .claude/skills/blog-fill-ssot/SKILL.md (can be listed with find .claude/skills -name 'SKILL.md').

Common Structure of the 3 Patterns and How to Prevent Them by Design

There is a common structure among the three patterns.

Common to all is the nature that “LLMs autonomously fill in blanks in instructions.” Blanks in design invite discretionary execution by LLMs. A tech lead’s job should be understood as the “eradication of blanks” rather than the “design of constraints.”

Pre-design checklist:

• Is there any contradiction among the three layers of CLAUDE.md (global / project / directory)?
• Are I/O contracts (inputs, outputs, forbidden operations) declared for each skill?
• Does the denyList in settings.json include SSOT files and infrastructure settings?
• Do bash prohibitions include destructive operations (force push, rm -rf)?

Dogfooding at Yakumo: Design Actually Working in Synapse

At Yakumo, we operate Synapse (a cross-functional agent organization built on Claude Code; responsible agents under .claude/agents/ + skill groups under .claude/skills/) on top of this 3-axis design.

Specific configuration examples:

Global CLAUDE.md: Rules for forbidden hardcoding, first-person narrative, and GitHub account switching.

Project CLAUDE.md (corporate-site): List of reference documents, develop branch convention, delegation rules, and a project-specific version of forbidden hardcoding.

Directory _README.md (src/content/magazine/): Physical structure of articles, mandatory frontmatter fields, and prohibition of slug changes.

settings.json denyList: src/_docs/, src/config/, .claude/, package.json.

Skill I/O Contract (blog-tech-write): Input is brief YAML only, output is blog-ops/output/ only, commit forbidden, direct writing to src/content forbidden.

With this design, even when the non-engineer representative uses Claude Code daily for article management and site updates, the state remains within the boundaries intended by the designer (tech lead).

In the last three months since the non-engineer representative started operating Claude Code daily, there have been 0 accidents derived from scope deviation. We see this as evidence that “prevention by design is working,” but we don’t yet have a mechanism to mechanically aggregate the count. In the future, we plan to add instrumentation to automatically count “how many times a defense was triggered” from gate logs and promote the fact that “we have been operating with 0 accidents” to an observable metric like “N attempts were stopped by the gate.”

Connecting to Sister Articles: Narratives of Management Judgment

This article is about “the technical theory on the side of tech leads who design and implement.” CLAUDE.md structural design, skill I/O contracts, and permission model settings—these all dealt with specific patterns that can be “written as designs.”

The axis of decision-making for “who to give this to,” “what business to start with,” and “at what stage to expand permissions” is the judgment on the side of management and PMs.

In the sister pillar, Organizational Design for Non-Engineers Using Claude Code, we write about the same design environment from the narrative of the “user side (non-engineers).” It deals with decision-making axes for how to use the environment the tech lead has prepared, such as the phased progress of skill delegation, transition conditions for Stages 1 to 3, and KPI settings.

Summary of Role Division:

When tech leads implement the 3-axis design in this article and non-engineers start using it according to the stage transition judgments in the sister pillar, this role division technically and organizationally guarantees the organizational deployment of Claude Code.

General design theory (architectural principles for harnesses) is handled in Design Principles for AI Agent Harnesses. This article specializes in patterns for “handing over to non-engineers” specific to Claude Code and is positioned as an implementation of harness design.

Summary: 3-Axis Design Principles for Tech Leads to Take Home

Claude Code deployment for non-engineers does not function just by “handing it over.” Designing the following three axes before handing it over is the minimum requirement for technical guarantees.

3-Layer Scoping of CLAUDE.md:

• global: Constraints across all projects (forbidden hardcoding, commit conventions).
• project: Project-specific references, delegation rules, and invariant conventions.
• directory _README.md: Scope restrictions per file and directory.

Skill I/O Contract:

• Input: Explicitly state parameters to receive and files that can be referenced.
• Output: Specifically declare writable paths.
• Forbidden Operations: Explicitly state Git operations and writing to out-of-range files.

3-Layer Permission Model:

• Read-only Zone: Protect SSOT files and infrastructure settings with a denyList.
• Write Guard: An allowList that minimizes the writable range.
• Bash Prohibitions: Explicitly forbid destructive operations (force push, rm -rf, infrastructure operations).

When all three are in place, delegation to non-engineers becomes “safe by design” for the first time. If any one of them is missing, the LLM will start autonomously filling in the blanks in instructions, and side effects unintended by the designer will silently accumulate.

The completion of design is not about “writing everything at the beginning.” Starting with minimum constraints, learning from accidents, and continuing to add—this improvement cycle itself is the essence of safe Claude Code deployment for non-engineers.