# How to Implement Path-Scoped Coding Rules for Different Directories

> Learn to implement path-scoped coding rules for directories using Markdown files and YAML front matter. Automatically enforce code quality with glob patterns and PostToolUse hooks.

- Repository: [Donchitos/Claude-Code-Game-Studios](https://github.com/Donchitos/Claude-Code-Game-Studios)
- Tags: how-to-guide
- Published: 2026-04-16

---

**Path-scoped coding rules are implemented by creating Markdown files with YAML front matter in `.claude/rules/` that specify glob patterns in a `paths` array, which the system automatically enforces through `PostToolUse` hooks when files matching those patterns are written or edited.**

Claude Code Game Studios uses a directory-specific enforcement system to ensure that gameplay code, engine core, UI components, and prototypes each follow distinct standards. By attaching rule definitions to specific path globs, the system automatically loads and validates relevant constraints whenever an agent modifies a file, eliminating the need for manual checklist verification.

## Understanding the Path-Scoped Rule Architecture

The mechanism relies on three interconnected components that work together during the `Write|Edit` lifecycle.

### Rule Files with YAML Front Matter

Individual rule definitions live in `.claude/rules/*.md` as Markdown files with YAML front matter. Each file declares its scope through a `paths` array containing glob patterns.

For example, [`.claude/rules/gameplay-code.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/rules/gameplay-code.md) targets all files under `src/gameplay/`:

```yaml
---
paths:
  - "src/gameplay/**"
  - "src/ai/**"
---

# Gameplay Code Rules

- No hard-coded balance values; use `BalanceData` resources
- All skill effects must implement `validate_skill_change()` hooks

```

### Rules Reference Documentation

The [`.claude/docs/rules-reference.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/docs/rules-reference.md) file serves as the human-readable index and machine-accessible registry. It contains a table mapping each rule file to its path patterns and enforcement scope, which the engine uses to discover applicable rules quickly.

### Settings and Hook Pipeline

The [`.claude/settings.json`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/settings.json) configures the validation trigger mechanism. It registers the `PostToolUse` hook pipeline that executes after file write operations:

```json
{
  "hooks": {
    "PostToolUse": [
      ".claude/hooks/validate-assets.sh",
      ".claude/hooks/validate-skill-change.sh"
    ]
  }
}

```

When an agent writes a file, these scripts parse the relevant rule files and block the commit if violations exist.

## Implementing a New Path-Scoped Rule

Follow these steps to create directory-specific enforcement for a new project section.

### Step 1: Create the Rule File

Create a Markdown file in `.claude/rules/` with a descriptive name. Start with YAML front matter defining the `paths` array using glob patterns:

```yaml
---
paths:
  - "prototypes/**"
---

# Prototype Code Rules

- Every prototype must contain a top-level `README.md` describing the hypothesis
- Source files may use `print()` for debugging, but **must not** contain production `assert` statements
- All exported assets **must** be listed in `assets/manifest.json` with a version tag

```

Save this as [`.claude/rules/prototype-code.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/rules/prototype-code.md).

### Step 2: Document in Rules Reference

Add an entry to [`.claude/docs/rules-reference.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/docs/rules-reference.md) to maintain the human-readable index:

```markdown
| Rule File | Path Pattern | Enforces |
|-----------|--------------|----------|
| `prototype-code.md` | `prototypes/**` | README presence, asset manifest, no production asserts |

```

### Step 3: Verify Hook Activation

Confirm that [`.claude/settings.json`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/settings.json) includes the validation script in the `PostToolUse` array. The [`validate-assets.sh`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/validate-assets.sh) script automatically discovers new rule files by scanning `.claude/rules/` and matching their `paths` globs against the modified file.

## How Validation Works at Runtime

When an agent attempts to write `prototypes/awesome/experiment.gd`, the enforcement chain activates automatically:

1. **Path Matching**: The [`validate-assets.sh`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/validate-assets.sh) hook scans `.claude/rules/` and identifies that [`prototype-code.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/prototype-code.md) has a `paths` entry matching `prototypes/**`.

2. **Rule Parsing**: The script extracts the Markdown content below the YAML front matter, parsing bullet points into discrete checks.

3. **Violation Detection**: If `prototypes/awesome/` lacks a [`README.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/README.md), the hook returns a blocking error:
   ```

   ❌ Violation: Prototype must contain a top-level README.md (see .claude/rules/prototype-code.md)
   ```

4. **Agent Correction**: The agent must create the missing [`README.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/README.md) and re-execute the write operation before the system allows the edit to persist.

This "May I write?" enforcement pattern ensures that path-scoped rules are checked before every file modification, maintaining codebase consistency without requiring manual review.

## Key Files and Their Roles

| File | Purpose | Location |
|------|---------|----------|
| `.claude/rules/*.md` | Stores individual path-scoped rule definitions with `paths` front matter | [`.claude/rules/`](https://github.com/Donchitos/Claude-Code-Game-Studios/tree/main/.claude/rules) |
| [`.claude/docs/rules-reference.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/docs/rules-reference.md) | Human-readable index and machine registry of all rules | [[`.claude/docs/rules-reference.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/docs/rules-reference.md)](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/docs/rules-reference.md) |
| [`.claude/settings.json`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/settings.json) | Configures the `PostToolUse` hook pipeline that triggers validation | [[`.claude/settings.json`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/settings.json)](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/settings.json) |
| [`.claude/hooks/validate-assets.sh`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/hooks/validate-assets.sh) | Executable script that parses rule files and enforces standards on `Write|Edit` operations | [[`.claude/hooks/validate-assets.sh`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/hooks/validate-assets.sh)](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/hooks/validate-assets.sh) |

## Summary

- **Path-scoped coding rules** are defined in Markdown files with YAML front matter located in `.claude/rules/`.
- The `paths` array in the front matter uses glob patterns to determine which directories a rule governs.
- **Automatic enforcement** occurs through `PostToolUse` hooks configured in [`.claude/settings.json`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/settings.json), specifically scripts like [`validate-assets.sh`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/validate-assets.sh).
- The **rules reference** at [`.claude/docs/rules-reference.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/docs/rules-reference.md) maintains the human-readable index and machine registry.
- Agents must resolve violations before writes are permitted, ensuring consistent standards across gameplay, engine, UI, and prototype directories.

## Frequently Asked Questions

### How do path-scoped rules differ from global coding standards?

Path-scoped rules allow different standards for different project areas, whereas global standards apply uniformly. In Claude Code Game Studios, the `paths` array in rule files enables specific requirements for `src/gameplay/**` (no hard-coded values) while allowing relaxed debug rules for `prototypes/**` (print statements permitted). This granularity prevents boilerplate in experimental code while enforcing rigor in production systems.

### What happens if a file matches multiple path patterns?

When a file matches multiple `paths` globs, the validation hook aggregates all applicable rules and enforces them collectively. For example, a file under `src/gameplay/ai/` might match both `src/gameplay/**` and `src/ai/**` patterns, triggering validation against both rule sets. The agent must satisfy all constraints before the write operation succeeds.

### Can I use regular expressions instead of glob patterns in the paths array?

The system uses standard glob patterns in the `paths` array, not regular expressions. Patterns like `prototypes/**` or `src/**/*_test.gd` follow glob syntax where `*` matches any characters within a segment and `**` matches across directory boundaries. For complex matching needs, create multiple specific glob entries rather than regex patterns.

### How do I test a new rule before committing it to the repository?

To test a rule locally, create the rule file in `.claude/rules/` with the `paths` array targeting a test directory, then attempt to write a file that violates the rule. The [`validate-assets.sh`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/validate-assets.sh) hook will immediately report the violation and block the write. Verify that the rule correctly matches intended paths by testing files inside and outside the glob patterns, then document the rule in [`.claude/docs/rules-reference.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/docs/rules-reference.md) once satisfied.