RomanNum3ral
/
claw-code
mirror of https://github.com/instructkr/claw-code.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
claw-code/.guardrails/docs/CLCODE_INTEGRATION.md

6.9 KiB
Raw Blame History

Claude Code Integration

This guide explains how to integrate Agent Guardrails with Claude Code using skills and hooks.

Overview

Claude Code supports:

  • Skills - JSON files that define specialized behaviors and constraints
  • Hooks - Shell scripts that run at specific lifecycle points

The setup script installs these configurations for you.

Setup

1. Install All Skills and Hooks

python scripts/setup_agents.py --install --platform claude

This creates:

.claude/
├── skills/
│   ├── guardrails-enforcer.json
│   ├── commit-validator.json
│   ├── env-separator.json
│   ├── scope-validator.json
│   ├── production-first.json
│   ├── three-strikes.json
│   └── error-recovery.json
└── hooks/
    ├── pre-execution.sh
    ├── post-execution.sh
    └── pre-commit.sh

2. Install a Single Skill

To install just one skill by name:

python scripts/setup_agents.py --install-skill guardrails-enforcer

Use --list-skills to see all available skill names:

python scripts/setup_agents.py --list-skills

3. Verify Installation

Check that skills are loaded:

ls -la .claude/skills/

Validate JSON syntax:

python -m json.tool .claude/skills/guardrails-enforcer.json

Check that hooks are executable:

ls -la .claude/hooks/

Skill File Format

Skills are JSON files in .claude/skills/. Each file has four fields:

Field Type Description
name string Unique identifier for the skill
description string What the skill does (shown in skill list)
tools array Allowed tools for this skill
prompt string Instructions injected into the session context

Example: guardrails-enforcer.json

{
  "name": "guardrails-enforcer",
  "description": "Enforces the Four Laws of Agent Safety: read-before-edit, stay-in-scope, verify-before-commit, halt-when-uncertain",
  "tools": ["Read", "Grep", "Glob", "AskUserQuestion"],
  "prompt": "# Guardrails Enforcement Agent\n\nYou are the Guardrails Enforcement Agent. You MUST enforce these rules on EVERY operation.\n\n## The Four Laws of Agent Safety\n\n1. **Read Before Editing** - Never modify code without reading it first\n2. **Stay in Scope** - Only touch files explicitly authorized\n3. **Verify Before Committing** - Test and check all changes\n4. **Halt When Uncertain** - Ask for clarification instead of guessing\n..."
}

The prompt field contains markdown-formatted instructions. Claude Code injects this into the session context when the skill is active.

Hook Details

Hooks are shell scripts that run automatically at specific points:

Hook When It Runs Purpose
pre-execution.sh Before file modifications Verify read-before-edit
post-execution.sh After file modifications Validate changes
pre-commit.sh Before git commit Validate commit message

Custom Hook Example

#!/bin/bash
# .claude/hooks/pre-commit.sh

# Run linter
npm run lint

# Run tests
npm test

# Check for secrets
trufflehog git file://. --since-commit HEAD

Make sure hooks remain executable:

chmod +x .claude/hooks/*.sh

Skill Reference

guardrails-enforcer

Enforces the Four Laws of Agent Safety. Halts on: unread code, scope violations, missing rollback, test/production mix, three consecutive failures.

commit-validator

Validates git commits. Checks: AI attribution (Co-Authored-By:), single focus per commit, no secrets in diff, tests pass.

env-separator

Enforces test/production separation. Detects: production DB connections in tests, shared instances, hardcoded production credentials.

scope-validator

Enforces scope boundaries. Only files explicitly authorized by the user or task description may be modified.

production-first

Requires production code before tests. Order: implementation, validation, tests, infrastructure.

three-strikes

Failure recovery protocol. After three consecutive failures, halts and escalates to user.

error-recovery

Error handling and recovery procedures. Provides structured guidance when operations fail.

Shared Prompts Reference

All skill prompts incorporate rules from the shared prompts directory:

Shared Prompt Used By Skills
skills/shared-prompts/four-laws.md guardrails-enforcer
skills/shared-prompts/halt-conditions.md guardrails-enforcer
skills/shared-prompts/three-strikes.md three-strikes
skills/shared-prompts/production-first.md production-first
skills/shared-prompts/clean-architecture.md guardrails-enforcer
skills/shared-prompts/cqrs.md guardrails-enforcer
skills/shared-prompts/scope-validation.md scope-validator
skills/shared-prompts/error-recovery.md error-recovery

When shared prompts are updated, re-run the setup script to regenerate skill prompts:

python scripts/setup_agents.py --install --platform claude

Customization

Adding a Custom Skill

  1. Create a new JSON file in .claude/skills/:
{
  "name": "my-skill",
  "description": "What it does",
  "tools": ["Read", "Bash"],
  "prompt": "Your instructions here..."
}
  1. Restart Claude Code to load the skill.

Disabling a Skill

Move it out of the skills directory:

mkdir -p .claude/skills/disabled
mv .claude/skills/commit-validator.json .claude/skills/disabled/

Restart Claude Code to apply.

Cloning a Single Skill from Another Repo

python scripts/setup_agents.py --clone .claude/skills/guardrails-enforcer.json

This copies a specific skill file by its repo path into the current project.

Installation Modes

Mode Command Behavior
Copy --mode copy (default) Writes standalone copies to the project
Symlink --mode symlink Creates symlinks back to this repo

Troubleshooting

Skills Not Loading

  • JSON syntax: python -m json.tool .claude/skills/*.json
  • Files in correct directory: ls .claude/skills/
  • Restart Claude Code after changes

Hooks Not Running

  • Check executable bit: chmod +x .claude/hooks/*.sh
  • Validate shell syntax: bash -n .claude/hooks/pre-execution.sh
  • Check hook names match expected patterns

Permission Denied

chmod +x .claude/hooks/*.sh

Best Practices

  1. One skill = one responsibility - Keep skills focused and composable
  2. Test hooks manually - Run scripts directly to verify behavior
  3. Regenerate after shared prompt updates - Re-run setup to sync skills
  4. Commit .claude/ to version control - Team shares the same guardrails

References