Security rules, cognitive scaffolding, and hook enforcement for Claude Code projects.
git clone https://github.com/Fieldnote-Echo/claude-secure-config.git
bash claude-secure-config/setup.sh /path/to/your-repoAdd .claude/rules/org/ to your .gitignore. Updates arrive automatically via git pull.
AI-generated code produces 1.7x more issues per PR than human code. 87% of AI-generated PRs contain security vulnerabilities. Developers who delegate to AI score 17% lower on comprehension — while those who use AI for conceptual inquiry score highest of all.
The problem isn't AI. It's AI without structure.
Layer 1: Hooks → "You can't do this" (deterministic enforcement)
Layer 2: Rules → "Here's how to do this" (security, hygiene, conventions)
Layer 3: Scaffold → "Why are we doing this?" (cognitive partnership)
Hooks are deterministic — they can't be ignored or summarized away.
| File | What it does |
|---|---|
hooks.md |
Blocks rm -rf, git push --force, --no-verify, .env access. Template settings.json you copy into your project. |
Text instructions the model follows during code generation. Structured as pre-flight checks, non-derivable specifics, and eval anchors.
| File | What it catches |
|---|---|
security.md |
Trust boundary violations, injection, XSS, unsafe deserialization, secret leaks, supply chain risks, MCP/tool trust |
code-hygiene.md |
Weak types, swallowed errors, fire-and-forget async, code duplication, unverified completion claims |
git-conventions.md |
Force-pushes, skipped hooks, git add ., scope creep, AI mis-attribution |
Shapes how the model works with you, not just what it produces.
| File | What it changes |
|---|---|
cognitive-scaffold.md |
Reduces sycophancy, surfaces trade-offs, flags unfamiliar patterns, monitors for dependency formation |
deliberation.md |
Pauses before irreversible actions, builds trust progressively, pushes back when something seems off |
task-protocol.md |
Preflight questions before non-trivial tasks |
~255 lines, ~2,922 tokens total. Compliance degrades as instruction volume grows — keep loaded rules concise and verify behavior after changes.
The quick start above uses symlinks (recommended). Other options:
| Method | Command | Updates |
|---|---|---|
| Copy | setup.sh /path/to/repo --copy |
Re-run to update |
| Manual | Copy individual files to .claude/rules/ |
Manual |
| @import | @/path/to/rules/security.md in CLAUDE.md |
Automatic (path must resolve on every dev machine) |
Run setup.sh --help for all flags. See the setup.sh reference for provenance tracking and advanced configuration.
Text rules can be ignored. Hooks can't. Copy the template from hooks.md into .claude/settings.json.
For isolation beyond hooks: Anthropic's built-in sandbox or Trail of Bits' devcontainer.
.claude/CLAUDE.md → Your critical project rules (top of file = highest attention)
.claude/rules/*.md → Your project-specific rules
.claude/rules/org/*.md → Shared rules from this repo
internal/*.md → Private rules (gitignored, install with --internal)
See the wiki for customization patterns, internal rules, and compaction survival.
- Not a replacement for SAST/DAST — these are authoring-time guardrails
- Not runtime security — implement CSP, rate limiting, and auth middleware in your code
- Text rules can be compacted away in long sessions — hooks are immune
--dangerously-skip-permissionsdisables all hooks and deny rules- AI training can override text instructions — hooks are stronger than rules
Built on OWASP Top 10:2025, OWASP Agentic Top 10, CWE Top 25, OpenSSF AI Code Assistant Guide, and research on cognitive scaffolding, deliberative alignment, and human-AI feedback loops.
PRs welcome. Keep rules generic, concise, and backed by data where possible. See the contributing guide for rule design principles and testing requirements.
MIT