Skip to content

QUICKSTART.md

Latest commit

 

History

History
103 lines (73 loc) · 2.92 KB

QUICKSTART.md

File metadata and controls

103 lines (73 loc) · 2.92 KB

Quickstart

From clone to working hooks in 5 minutes.

1. Clone and open

git clone https://github.com/Bluepandafox/claude-code-production-patterns
cd claude-code-production-patterns

Open Claude Code in this directory. The SessionStart hook fires immediately and prints a session brief (it will be empty since no tracker.md exists yet -- that's expected).

2. Verify hooks are registered

# Check that settings.json is wired up
cat .claude/settings.json

You should see hooks registered for SessionStart, PreToolUse, and PostToolUse.

3. Run the hygiene audit

python scripts/hygiene_audit.py

On a fresh clone, expect 4 WARNs: skills directory missing, MANIFEST.sha256 not found, tracker.md missing, follow_ups.md missing. These are files you create as you customize the project. Zero FAILs means the architecture is intact.

4. Customize for your project

Step A: Edit CLAUDE.md Replace the placeholder skill descriptions with your own skills and trigger phrases.

Step B: Update paths in session_start.py Change TRACKER_PATH, FOLLOWUPS_PATH, and LEARNING_LOG_PATH to match your project's file layout.

Step C: Update is_quality_target() in quality_check.py Tell the quality gate which files to check. Default is output/ and reports/ directories.

Step D: Customize banned_patterns.md Add or remove patterns for your domain. The quality gate will pick them up automatically.

Step E: Create your tracker Create tracker.md with this format:

## **Project Name**
**Status:** 🟡 In Progress

## **Another Project**
**Status:** ✅ Done

Run the session brief manually to confirm it reads correctly:

echo '{}' | python .claude/hooks/session_start.py

5. Add your skills

mkdir .claude/skills/my-skill

Create SKILL.md with frontmatter:

---
name: my-skill
description: One-line description of what this skill does
trigger: "do X", "run X", "start X"
---

# My Skill
...workflow steps...

The architecture guard will enforce that you stay under 10 user-facing skills.

6. Run tests

python -m pytest tests/ -v

All tests should pass on a fresh clone. Add tests as you extend the hooks.

Troubleshooting

Hook not firing:

  • Check settings.json has the hook registered for the right event
  • Check the hook file exists at the path in the command string
  • Run python scripts/hygiene_audit.py to surface configuration issues

Architecture guard blocking a write:

  • Read the block message -- it will cite the specific rule being violated
  • Check .claude/ARCHITECTURE.md for the rule's rationale
  • Fix the underlying issue rather than disabling the guard

Quality gate blocking a write:

  • The violation list tells you exactly what to fix
  • Run python scripts/hygiene_audit.py --json for machine-readable output
  • If a check is wrong for your domain, update is_quality_target() to exclude that path