Global Instructions

I am not a developer. I build projects by describing what I want in plain language. Treat me as a smart, capable person who does not know programming terminology or conventions. These rules apply to every project.

For full personal context, business details, team info, and preferences, read ~/Claude-Memory/CLAUDE.md and the sub-files it points to.

Security (Critical)

API Keys and Secrets

• NEVER hardcode API keys, passwords, tokens, or secrets in code files
• ALWAYS use .env files for secrets and add .env to .gitignore immediately
• Before any git command on a file headed to GitHub, check that no secrets are included
• If I accidentally paste an API key into chat or a file, warn me immediately and help me rotate it

Package Installation — How to Report Findings

A hook intercepts every npm install, npm i, pnpm add, pnpm install, pnpm i, yarn add, pip install, and pip3 install command and runs a Socket.dev security check before anything installs. When the hook blocks an install and returns findings, report them in this format:

Package: [name] What it does: [one sentence] Weekly downloads / last updated: [from Socket.dev or web] Socket.dev findings: [exact output from the hook, in plain English] Verdict: SAFE / CAUTION / DO NOT INSTALL / UNVERIFIED Reasoning: [plain English, no jargon]

Then stop and wait for me to type “yes, install it” or “go ahead.” Do not retry the install for any other reason.

If Socket.dev was unreachable and returned no data, your verdict must be UNVERIFIED — search the web for “[package name] security vulnerability” and “[package name] supply chain attack,” include what you find, and still wait for my approval.

Automatic DO NOT INSTALL Triggers

If any of these are present, verdict must be DO NOT INSTALL and you must tell me why before asking anything:

• Supply chain risk or malware flagged on Socket.dev
• Typosquatting warning
• Critical or high severity vulnerability in the current version
• Recently transferred to a new maintainer with no track record
• Fewer than 50,000 weekly downloads for a package claiming wide adoption
• No updates in over a year (unless it is a stable, finished utility)
• Requests unnecessary system-level permissions

Transitive Dependencies

If installing Package A also pulls in B and C automatically, check all of them. If you can’t feasibly check them all, list every package that will be installed and tell me before proceeding.

Scripts and Network Requests

• Never run a script downloaded from the internet without first explaining exactly what it does, line by line if needed
• If code makes network requests to external services, tell me which services, what data is sent, and why, before running it

Safety and Confirmation

• Before deleting, overwriting, or significantly changing existing files, tell me what’s affected and ask for confirmation
• Before any command that modifies system settings, installs global software, or changes config outside the project folder, explain it and ask for confirmation
• A hook blocks git push --force, git reset --hard, and rm -rf. If you need one, explain why and ask for my explicit approval before retrying
• If you’re unsure about the right approach, ask me rather than guessing

Code Quality

• Keep code simple and readable; prefer straightforward solutions over clever ones
• Add brief comments explaining what each section does so I can follow along
• Start with the simplest working version, then improve
• Don’t add features, complexity, or “improvements” I didn’t ask for
• If you spot a problem in my existing code, tell me — don’t silently fix it
• Database: PostgreSQL — don’t add a database unless I specifically ask
• I don’t want my apps to be able to fail silently. Build in error tracking and notifications so a failure reaches me instead of sitting quietly in a log

Project Organisation

• Keep files in clear folders with obvious names; explain the structure for new projects
• Always create a .gitignore that excludes node_modules and other standard ignores
• If a project has no version control, suggest it and explain why it matters

Three roots: ~/Code, ~/AI-Work, ~/CoWork

My work splits across three folders that share one relative path, so swapping the root gets you the matching half — no lookup needed. ~/Code/Project A/ pairs with ~/AI-Work/Project A/.

• ~/Code — code. Everything here goes to GitHub. Technical documentation stays in the repo beside the code.
• ~/AI-Work — the Obsidian vault: briefs, build prompts, design prompts, planning notes. Syncs to my phone. Read it when you need project background, not by default.
• ~/CoWork — data files I work on with Claude: spreadsheets, exports, client reports. Never goes to GitHub. Backed up to cloud storage instead.

Read access to ~/AI-Work and ~/CoWork is granted once in ~/.claude/settings.json, so no folder needs adding to any project.

Never put client data or any non-code files in ~/Code. A folder there can be committed and pushed by accident; ~/CoWork cannot. Never git init anything inside ~/CoWork.

Dependencies and Packages

• Prefer well-known, actively maintained packages with large communities
• Before adding a dependency, check if the functionality already exists or can be done simply without one
• Warn me about deprecated or archived packages
• When updating packages, explain what changed and what might break

Error Handling

• Explain errors in plain language first, then suggest fixes
• Don’t silently catch and hide errors — I need to know when things go wrong
• If an approach isn’t working after two attempts, stop and explain rather than trying endless variations

Backup and Recovery

• Before large changes to a working project, suggest a backup or git commit
• Never overwrite working code without a way to get it back
• If I ask you to undo something, explain what will be restored and what might be lost

Memory

At the end of each session, write a 5–8 bullet summary of what was completed and what’s still pending to context-log.md in the project root. Create the file if it doesn’t exist.

One event, one home

Writing the same event into four files gives you four accounts that drift apart as the code moves on. Each kind of record has exactly one home:

A file that accumulates dated ## headings is in the wrong shape. A manual whose sections are dates is a changelog wearing a manual’s name — ask it “how does login work?” and you get every historical account to reconcile instead of one answer.

Keep this file small

CLAUDE.md is prepended to every session, so anything appended here is paid for on every future run, forever. Ceiling ~25 KB, target under 200 lines — past that, adherence drops as well as budget. Only two things earn a place: a rule that changes what a future session may do, or a trap that would otherwise cost another incident. Corrections replace the wrong text rather than sitting beside it; git holds the history. Run wc -c CLAUDE.md before you commit.

Two mechanisms genuinely defer cost, and @import is not one of them — imports load at launch, so they organise without saving anything. Skills load only when invoked, and .claude/rules/*.md with paths: frontmatter load only when a matching file is read.

⚠️ Never move a safety rule into a path-scoped rule file to shrink this one. Path-scoped rules are not re-injected after /compact, while a project-root CLAUDE.md is. A long autonomous run compacts repeatedly, so a permission boundary or deploy guardrail moved there would silently stop applying part-way through — a control that reads as enforcement and executes nothing. Fine for file-type conventions, never for rules.

Never load a log file at session start

Two hooks assist, and neither blocks — both only print. session-snapshot.sh (SessionStart) prints about 1.4 KB of computed state: branch, uncommitted count, recent commits, recent session titles sorted by date, and any open ## Needs Human items. It never opens a log file. session-log-check.sh (Stop) measures what the session actually appended and reports one of: nothing written, more than 4 KB written, or the live log past 150 KB so rotation is due.

No context log is auto-loaded. Open one yourself when you need prior-session history — and never read it whole. A 250 KB log costs roughly 62,000 tokens to read, half a context window, to find one paragraph. Instead:

1. grep -n '^## ' context-log*.md — the index. Every entry is a dated heading. The * is load-bearing in any project that has rotated: without it you silently stop at the current period and still get results.
2. Read only that line range, or grep -n -i '<term>' context-log*.md to search by topic and read around the hits.

Sort that index by date, not by position — sessions append to both the top and the bottom of these files, so head or tail alone can miss the newest entry.

Rotation. When context-log.md passes ~150 KB, or at a quarter boundary, move the oldest complete period into context-log-<YYYY>-Q<n>.md beside it at the project root — flat, never a subdirectory, because entries contain relative links that a depth change would break. Archives are frozen; append only to context-log.md. Two things to check before your first rotation, both of which fail silently, are in the memory note.

Skills

• Available skills are injected into context at session start. Keep a human-readable inventory at ~/.claude/skills-inventory.md.
• Custom skills trigger ONLY on explicit invocation — never on a casual phrase. Any skill that can run unattended must pause at a confirmation gate first.
• /graphify: when I type it, invoke the graphify skill before anything else. When you need to understand a codebase, read the knowledge graph first.

Agent Team Policy

Propose an agent team when: the task has 3+ clearly independent workstreams, parallel research benefits from multiple perspectives, or changes cross layers (frontend + backend + tests).

Do NOT spawn a team for: tasks under ~30 min of single-agent work, same-file edits, or sequential tasks with hard dependencies.