convez.ai
Skill
wuykjl

rulehook

wuykjl/rulehook

Ver no GitHub
InicialPluginScore · de 0 a 100

rulehook — 把 Claude Code 的 rules 变成 hooks。三层防线:skill 预防 + Stop 实时拦截 + SessionStart 趋势预警。零 token 成本,零外部依赖。

Instalação

$npx convez-ai wuykjl/rulehook

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

rulehook

Turn Claude Code rules into hooks. Catch rule violations before you see them. Zero tokens, zero servers.

What it does

Claude Code has rules (in .claude/rules/) and memories (in memory/). But rules are soft constraints — the agent often skips them under engineering momentum. rulehook bridges the gap: it watches the transcript for rule violations and injects a reminder before the response reaches you.

Architecture — three defence lines

L1: SKILL.md prevention → "Before generating a document, ask the user which template"
    └─ Inserted at the TOP of a skill's SKILL.md — agent sees it immediately

L2: Stop hook real-time intercept → grep transcript tail for doc-gen patterns
    └─ 95% of responses pass through silently (~10 ms). On hit → systemMessage warning

L3: SessionStart trend warning → read observations.jsonl, compute compliance rate
    └─ If your compliance is < 85% over the last 14 days, inject additionalContext

Install

1. Copy hooks

cp hooks/stop-doc-template-check.js ~/.claude/scripts/hooks/
cp hooks/session-start-compliance-audit.js ~/.claude/scripts/hooks/

2. Register in settings.json

Add to ~/.claude/settings.json:

"hooks": {
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "node \"~/.claude/scripts/hooks/session-start-compliance-audit.js\"", "timeout": 15 }],
      "id": "session-start:compliance-audit"
    }
  ],
  "Stop": [
    {
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "node \"~/.claude/scripts/hooks/stop-doc-template-check.js\"", "timeout": 15 }],
      "id": "stop:doc-template-check"
    }
  ]
}

3. Add L1 prevention to relevant skills

Open the SKILL.md of any document-generation skill (e.g. ~/.claude/skills/docx/SKILL.md) and insert at the top:

## ⚠️ PRE-GENERATION CHECK (MANDATORY — DO NOT SKIP)

**Before writing any document generation code**, you MUST:
1. Read memory/<rule-name>.md
2. Ask the user: "<checklist question>"
3. Wait for user confirmation before proceeding

See skills/PRE-GENERATION-CHECK.md for the full template.

4. Verify

node tests/simulate-all.js   # 6 scenarios — should be 100% pass
node tests/simulate-edge.js  # 6 edge scenarios

How it works

User says "make a Word doc"  ──→  L1 fires (skill PRE-GENERATION CHECK)
                                      │
Agent generates docx file    ──→  Stop hook fires
                                      │
                              Stage 1: grep transcript tail for doc patterns
                                      │ 95% of responses → silent pass
                                      │ 5% hit → check compliance
                                      │
                              Stage 2: check if template was discussed
                                      │ Yes → silent pass
                                      │ No → systemMessage warning
                                      │
Next session starts          ──→  SessionStart hook reads observations.jsonl
                                      │
                              Calculates: "Past 14 days, 40% compliance"
                              → injects additionalContext
                              → Agent starts session already aware

Adding your own rules

Edit hooks/session-start-compliance-audit.js → RULES object:

const RULES = {
  'my-rule': {
    name: 'My Rule Name',
    triggerPatterns: [/pattern.*that.*indicates.*action/],
    compliancePatterns: [/pattern.*for.*correct.*behavior/],
  },
};

One JSON entry per rule. No other changes needed.

Cost

Per response
CPU~10 ms (Node.js grep)
Token0 (only a 50-token systemMessage on violation)
Dependencies0 (Node.js stdlib only)

Known Limitations

This is an honest, externally-reviewed assessment. None of these are bugs — they are deliberate design tradeoffs or areas awaiting real-world validation.

LimitationImpactWhy it exists
Claude Code onlyHook registration format (settings.json SessionStart/Stop) is bound to Claude Code. Cannot be directly ported to Cursor, Codex, or other agent platforms.Architectural choice, not a bug. The correct cross-platform path is to extract a platform-agnostic rule schema and write per-platform adapters — like ESLint's parser/plugin model.
Cross-turn matching blindspotTemplate discussion in turn 3 + doc generation in turn 99 (outside the 500-line scan window) → L2 may false-positive.Deliberate. Scanning the full transcript would break the 10ms performance guarantee. Mitigated by non-blocking systemMessage — Claude can judge false positives itself.
L3 depends on observe.sh data pipelineSessionStart compliance audit reads observations.jsonl. New deployments with no ECC observe.sh history see no data → L3 silently degrades (by design: no data = no false alarms).The audit script gracefully skips when no data exists. For standalone use, rulehook can record its own observations — this is a planned improvement, not a permanent dependency.
Single real-rule exampleOnly word_templates_choice has been deployed end-to-end. Pressure testing with 10 synthetic rules proves performance scales, but real-world multi-rule behavior (pattern conflicts, threshold coupling, alert noise) hasn't been validated.This is the next phase. The RULES object architecture is designed for N rules — but "designed for" ≠ "battle-tested with."
Regex-based detectionTrigger and compliance patterns are hand-written regular expressions. False negatives occur if the agent expresses the same behavior using different phrasing.LLM-assisted pattern generation is an obvious next step. The two-stage architecture reserves "Stage 2" for exactly this — swap regex for a focused LLM call when accuracy demands it.

Ecosystem

rulehook enforces rules. But what rules?

ECC — a mature, layered rule system covering 12+ languages (TypeScript, Python, Go, Rust, React, web, and more). Common rules define universal standards; language-specific rules override where idioms differ. 34 rule files with multi-language (EN/ZH) support.

ecc-rules: WHAT to check rulehook: HOW to enforce common/coding-style.md RULES object in session-start-compliance-audit.js typescript/coding-style.md triggerPatterns + compliancePatterns web/design-quality.md L1: SKILL.md injection / L2: Stop hook grep / L3: SessionStart audit

Combine them: install ecc-rules for the standards, configure rulehook to enforce them. Together they close the loop: rules define what is expected, hooks ensure it happens.

File map

FileRole
hooks/stop-doc-template-check.jsL2: two-stage transcript audit
hooks/session-start-compliance-audit.jsL3: historical compliance rate
skills/PRE-GENERATION-CHECK.mdL1 template snippet
config/settings-snippet.jsonHook registration example
tests/16+ scenarios, 100% pass
docs/三层防线机制.mdFull design doc (Chinese)

License

MIT

Ver o original no GitHub

Bom para

Relacionados