DEV Community: Gabriele Mariotti

Claude Code hooks: how to protect your prod environments without blocking every command

Gabriele Mariotti — Fri, 24 Apr 2026 10:50:35 +0000

Gabriele Mariotti

Apr 24

Guardrails with hooks: how I protect AWS production profiles in Claude Code

#claude #aws #security #devops

Comments 1

4 min read

Guardrails with hooks: how I protect AWS production profiles in Claude Code

Gabriele Mariotti — Fri, 24 Apr 2026 10:44:11 +0000

The problem

When Claude Code runs a Bash command, it checks permissions before executing. You have two broad options:

Approve every AWS command manually — safe, but you'll be clicking "Allow" dozens of times a day, even for harmless aws s3 ls calls on dev buckets.
Add Bash(aws *) to the allow list — zero friction, but now every production command runs without any confirmation gate.

Neither is great. You want Claude to move fast on dev and staging, but you need a hard stop before anything touches production.

The goal

Allow all AWS CLI commands by default. Force an explicit confirmation only when a command targets a specific production profile. No changes to the daily workflow — prod is the only thing that needs friction.

The solution

What is `settings.json`?

Claude Code reads a settings.json file (global at ~/.claude/settings.json, or per-project at .claude/settings.json) that controls permissions, hooks, environment variables, and more. The permissions section lets you define which tool calls are allowed, denied, or always require confirmation.

{
  "permissions": {
    "allow": [
      "Bash(aws *)"
    ]
  }
}

This blanket rule tells Claude: run any aws command without asking. That's the starting point — broad permission, then we layer in selective protection via a hook.

Official docs: Settings & Permissions

What is a hook?

Hooks are shell commands that Claude Code fires at specific lifecycle events. The most useful for this case is PreToolUse: it runs before Claude executes a tool call, and can influence what happens next.

Claude passes the tool input as JSON on stdin. Your hook reads it, inspects it, and can return a JSON response that tells Claude to allow, deny, or ask the user for confirmation.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(aws *)",
            "command": "~/.claude/hooks/aws-prod-guard.sh"
          }
        ]
      }
    ]
  }
}

Two filters work together here. The outer matcher: "Bash" selects the tool type. The inner "if": "Bash(aws *)" is a pre-filter that only invokes the script when the actual command starts with aws — so Claude doesn't spawn the shell script on every single Bash call (git, npm, make, etc.). Only AWS commands reach the guard.

Official docs: Hooks

The guard script

The script reads the command Claude is about to run, checks whether it targets a protected profile, and responds accordingly.

~/.claude/hooks/aws-prod-guard.sh

#!/bin/bash
# Intercepts Bash tool calls and asks for confirmation when an AWS command
# targets a production profile. Edit aws-prod-profiles.json to add/remove profiles.

PROFILES_FILE="$(dirname "$0")/aws-prod-profiles.json"
[ -f "$PROFILES_FILE" ] || exit 0

CMD=$(jq -r '.tool_input.command // ""')

while IFS= read -r entry; do
  profile=$(echo "$entry" | jq -r '.profile')
  account=$(echo "$entry" | jq -r '.account')
  description=$(echo "$entry" | jq -r '.description')

  if echo "$CMD" | grep -qE "(--profile[[:space:]=]+$profile|AWS_PROFILE[[:space:]]*=[[:space:]]*$profile|AWS_DEFAULT_PROFILE[[:space:]]*=[[:space:]]*$profile)"; then
    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Production profile detected: %s — %s (account %s)"}}\n' \
      "$profile" "$description" "$account"
    exit 0
  fi
done < <(jq -c '.[]' "$PROFILES_FILE")

exit 0

The key detail: when a production profile is detected, the hook returns permissionDecision: "ask" — which tells Claude to pause and prompt the user for explicit approval, overriding the blanket allow rule from settings.json. If no protected profile is matched, the hook exits 0 with no output and Claude proceeds normally.

The profiles file

Protected profiles live in a separate JSON file, so you can add or remove entries without touching the script.

~/.claude/hooks/aws-prod-profiles.json

[
  {
    "profile": "my-production",
    "account": "000000000000",
    "description": "Main production account"
  }
]

Add as many profiles as you need. The account and description fields are included in the confirmation message Claude shows the user, making it clear exactly what is about to be touched.

The key insight

The real value of hooks is not blanket blocking — it is interception at the right boundary. You let everything through until it reaches a dangerous environment, then you step in with an ask (or a hard deny if you prefer zero tolerance).

This gives you surgical control: Claude moves freely across dev and staging, but the moment a production profile appears in a command, the hook fires and puts a human back in the loop. The dangerous part gets flagged; everything else stays frictionless.

File structure

~/.claude/
├── settings.json          # permissions + hook registration
└── hooks/
    ├── aws-prod-guard.sh  # the guard script (chmod +x)
    └── aws-prod-profiles.json  # list of protected profiles

~/.claude/settings.json — registers the hook and grants the broad AWS permission:

{
  "permissions": {
    "allow": ["Bash(aws *)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(aws *)",
            "command": "~/.claude/hooks/aws-prod-guard.sh"
          }
        ]
      }
    ]
  }
}

~/.claude/hooks/aws-prod-profiles.json — the only file you need to edit to add or remove protected profiles:

[
  {
    "profile": "my-production",
    "account": "000000000000",
    "description": "Main production account"
  }
]

~/.claude/hooks/aws-prod-guard.sh — the guard script (see above).

One repo, multiple AI agents: a tool-agnostic pattern for shared AI guidelines

Gabriele Mariotti — Sat, 11 Apr 2026 21:02:11 +0000

The problem

Every AI coding tool has its own way to receive project context:

Kiro → .kiro/steering/*.md
Claude Code → CLAUDE.md + .claude/rules/*.md
Cursor → .cursor/rules/*.md

If your team uses different tools — or if you want to switch without rewriting everything — you have a problem. You either:

Duplicate the same rules in every format → they diverge within days
Pick one tool and lock everyone in → someone is always excluded
Put rules in README and hope agents read it → they don't, reliably

None of these scale.

The pattern

Apply separation of concerns to AI agent configuration:

my-project/
├── ai/                          ← Knowledge (tool-agnostic, in git)
│   ├── README.md
│   └── terraform.md
├── .kiro/steering/              ← Kiro adapter (in git)
│   ├── ai-guidelines.md
│   └── use-terraform.md
├── .kiro/steering/local/        ← Kiro personal overrides (gitignored)
│   └── status.md
├── .claude/rules/               ← Claude adapter (in git)
│   └── tech-use-terraform.md
├── CLAUDE.md                    ← Claude shared instructions (in git)
└── CLAUDE.local.md              ← Claude personal overrides (gitignored)

Three layers:

Layer	Purpose	In git?
`ai/`	What to do (knowledge)	✅ Yes
`.kiro/steering/`, `.claude/rules/`	How to load it (adapters)	✅ Yes
`local/`, `CLAUDE.local.md`	Personal context (overrides)	❌ No

The knowledge layer: `ai/`

This is the single source of truth. Files here are:

Tool-agnostic — no references to Kiro, Claude, or any specific agent
Human-readable — standard markdown, useful even without an AI tool
Domain-focused — one file per topic (Terraform, security, API design, etc.)

Example — ai/terraform.md:

# Terraform — Steering rules

## Folder structure
Each folder is an independent Terraform root module...

## Standard files per module
Every module must contain: main.tf, variables.tf, outputs.tf, versions.tf, README.md...

## Security rules
### IAM — least privilege
- Scope resource ARNs to the specific project/environment — never "*" unless the API requires it...

No tool-specific syntax. No frontmatter. Just knowledge.

The adapter layer

Adapters are minimal files — 3-5 lines — that tell each tool when and where to load the knowledge.

Kiro adapter (`.kiro/steering/use-terraform.md`)

---
inclusion: fileMatch
fileMatchPattern: ["**/*.tf", "**/*.tfvars"]
---

# Terraform rules

Read and apply the rules in `ai/terraform.md` for all Terraform-related work.

Kiro loads this only when you're working on .tf files. The actual rules live in ai/terraform.md.

Claude adapter (`.claude/rules/tech-use-terraform.md`)

---
globs: ["**/*.tf", "**/*.tfvars"]
---

# Terraform Rules

Read and follow the guidelines in `ai/terraform.md` before doing any Terraform work.

Same concept, different syntax. Both point to the same source.

Meta-adapter: teaching agents the pattern

One file tells each agent how the system works:

Kiro (.kiro/steering/ai-guidelines.md):

---
inclusion: always
---

# AI Guidelines Convention

Technical guidelines are in `ai/` — tool-agnostic, single source of truth.

## Structure
- `ai/<topic>.md` ← domain knowledge
- `.kiro/steering/` ← Kiro adapters (in git)
- `.kiro/steering/local/` ← personal overrides (gitignored)

When updating a guideline, modify only `ai/<topic>.md`.

Claude (CLAUDE.md):

# My Project

## AI Guidelines Convention
Technical guidelines are in `ai/` — tool-agnostic, single source of truth.
Adapters in `.kiro/steering/` (Kiro) and `.claude/rules/` (Claude Code).
Personal overrides: `.kiro/steering/local/` and `CLAUDE.local.md` — not in git.

When updating a guideline, modify only `ai/<topic>.md`.

The personal layer

Some context is personal or sensitive:

Project status and TODOs
Credentials and environment config
Personal preferences and workflow notes

This goes in tool-specific locations that are gitignored:

Tool	Personal location	Gitignore rule
Kiro	`.kiro/steering/local/`	`.kiro/steering/local/`
Claude	`CLAUDE.local.md`	`CLAUDE.local.md`

The `.gitignore`

# Kiro
.kiro/*
!.kiro/steering/
.kiro/steering/local/

# Claude
CLAUDE.local.md

This tracks .kiro/steering/ (adapters) but ignores .kiro/steering/local/ (personal).

Why this works

Single source of truth

Change ai/terraform.md once → every agent picks it up. No drift, no sync issues.

No vendor lock-in

Switch from Kiro to Claude? The knowledge stays. Add Cursor tomorrow? Write a 3-line adapter.

Team-friendly

Everyone sees the same rules
New team member clones the repo → gets all the knowledge immediately
Personal overrides don't pollute the shared config

Progressive adoption

Start with one file in ai/. Add adapters as needed. The pattern scales from 1 file to 50.

Human-readable

ai/ is just markdown. No frontmatter, no tool syntax. A developer without any AI tool can read it and follow the same conventions.

Adding a new domain

Create ai/new-topic.md with the rules
Create adapter for each tool:
- .kiro/steering/use-new-topic.md (with appropriate inclusion mode)
- .claude/rules/tech-use-new-topic.md (with appropriate globs)
Commit all three files

Time: 2 minutes. The knowledge is written once, loaded everywhere.

Conclusion

The insight is simple: knowledge and configuration are different concerns. Knowledge is what your project needs. Configuration is how a specific tool loads it.

Separate them, and you get:

One place to maintain rules
Freedom to use any AI tool
Clean git history (knowledge changes are meaningful, adapter changes are rare)
Team alignment without tool alignment

The ai/ folder is your project's brain. The adapters are just plugs.

DEV Community: Gabriele Mariotti

Claude Code hooks: how to protect your prod environments without blocking every command

Guardrails with hooks: how I protect AWS production profiles in Claude Code

Guardrails with hooks: how I protect AWS production profiles in Claude Code

The problem

The goal

The solution

What is settings.json?

What is a hook?

The guard script

The profiles file

The key insight

File structure

One repo, multiple AI agents: a tool-agnostic pattern for shared AI guidelines

The problem

The pattern

The knowledge layer: ai/

The adapter layer

Kiro adapter (.kiro/steering/use-terraform.md)

Claude adapter (.claude/rules/tech-use-terraform.md)

Meta-adapter: teaching agents the pattern

The personal layer

The .gitignore

Why this works

Single source of truth

No vendor lock-in

Team-friendly

Progressive adoption

Human-readable

Adding a new domain

Conclusion

What is `settings.json`?

The knowledge layer: `ai/`

Kiro adapter (`.kiro/steering/use-terraform.md`)

Claude adapter (`.claude/rules/tech-use-terraform.md`)

The `.gitignore`