Setting up Claude Code for safe PHP development

A tutorial. Follow it top to bottom and you'll have Claude Code installed, the three UserSpice skills wired up, a project-level CLAUDE.md teaching the framework's conventions, the right Bash permissions so the skills don't prompt every five seconds, and a first audit run completed against a real codebase. Expect 20–30 minutes the first time.

What you'll have at the end: every Claude session in this project starts with the framework context, can audit and scaffold without permission-prompting, and produces code that passes the security checklist on day one.

Prerequisites

A UserSpice project (6.0.9+) checked out locally, or any PHP project you want to apply the same pattern to.
An Anthropic API key or a Claude Code subscription. Either authentication path works.
A bash environment — native on Linux/macOS, Git Bash or WSL on Windows.
Git, for cloning the skills repo.

Step 1 — Install Claude Code

The official installer:

curl -fsSL https://claude.ai/install.sh | sh

Restart your terminal, then verify:

claude --version

If you see a version number, you're done with this step. If you don't, the installer probably wrote to a directory that's not in your $PATH — check ~/.local/bin and add it to your shell's startup file.

Authentication is interactive on first run. Just type claude in a project directory and it'll prompt you through whichever flow your account uses.

Step 2 — Install the three UserSpice skills

The skills live at github.com/UserSpice-AI/userspice-claude-skills. Clone the repo and drop each skill folder into ~/.claude/skills/:

git clone https://github.com/UserSpice-AI/userspice-claude-skills.git mkdir -p ~/.claude/skills cp -r userspice-claude-skills/userspice-audit ~/.claude/skills/ cp -r userspice-claude-skills/userspice-helper-lookup ~/.claude/skills/ cp -r userspice-claude-skills/userspice-page-scaffold ~/.claude/skills/

Restart any running Claude Code sessions. To verify, open a fresh Claude session in any directory and type /. The three commands should appear in the suggestion list:

/userspice-audit — walk custom code for security issues
/userspice-helper-lookup — find the canonical signature for a UserSpice helper
/userspice-page-scaffold — generate a security-correct page on day one

Step 3 — Drop CLAUDE.md into your project

This is the single biggest leverage point. A file at the root of your project that Claude reads on every session, telling it what framework you're on and what conventions to follow.

A starter for a UserSpice project:

# Save as ./CLAUDE.md at the root of your UserSpice project.

## UserSpice AI Prompts

This is a UserSpice site. Before doing substantive work, read:

  /usersc/plugins/ai_prompts/prompts/00_start_here.md.php

That file indexes the available task-specific prompts. Each is a
.md.php file with a one-line PHP wrapper — skip the wrapper and
read the markdown below.

Local overrides may live alongside in:

  /usersc/plugins/ai_prompts/custom_prompts/

Files there with the same name win over the shipped versions.

## Available skills

- /userspice-audit          — audit custom code for security
- /userspice-helper-lookup  — find the canonical helper signature
- /userspice-page-scaffold  — generate a security-correct page

Put that file at the root. Verify Claude reads it by starting a new session and asking it "what framework is this project on?" — it should answer "UserSpice" and reference reading the prompts.

If you're not on UserSpice, the same pattern works — write a CLAUDE.md describing your stack's conventions, the helpers you use most often, and the anti-patterns to avoid. See the framework context page for what good content looks like.

Step 4 — Configure the Bash permissions allowlist

The skills use find and grep to locate UserSpice installs, walk file trees, and pull helper signatures. By default, Claude Code prompts before running any Bash command. After the first audit run, the skill offers to add the relevant entries to your settings.json — or you can do it preemptively:

# Edit ~/.claude/settings.json — create the file if it doesn't exist:
{
  "permissions": {
    "allow": [
      "Bash(find:*)",
      "Bash(grep:*)"
    ]
  }
}

Save, restart your Claude session. The skills should now run without prompting for find / grep permissions.

Project-level alternative: <project>/.claude/settings.json applies only within that project. Useful if you want the permissions scoped per-project rather than global.

Step 5 — Run your first audit

cd into your UserSpice project directory and start Claude:

cd ~/projects/your-userspice-site claude

Inside the session, type:

/userspice-audit

The skill will:

Walk up from the current directory looking for users/init.php to find the install root.
Verify the UserSpice version meets the floor (6.0.9+) and warn if below.
Ask which folder to audit (default: the whole project, minus framework/vendor).
Show you the plan (file counts by bucket — app, plugins, AJAX parsers).
Run the audit. For larger projects it dispatches parallel subagents per plugin / per app-folder chunk.
Write a dated markdown report to _noupload/audit-reports/audit-report-YYYY-MM-DD.md.
Print a summary in chat — counts by severity, top three rules violated, path to the full report.

The first run usually surfaces a non-zero count of findings even on a clean-looking codebase. That's expected — the audit checklist is comprehensive. Read the report, triage what matters, and use the file:line references to jump straight to the code.

Day-to-day workflow

Once setup is done, the workflow on every feature looks like:

Generate. Ask Claude to build the thing. Because CLAUDE.md is loaded, it generates UserSpice-idiomatic code, not generic PHP.
Scaffold. For new pages, use /userspice-page-scaffold instead of asking for the page from scratch. The scaffold stamps out the right structure (init.php, securePage, CSRF, validation) with one prompt.
Look up. When you (or Claude) is unsure of a helper signature, /userspice-helper-lookup <name> reads the canonical signature live from the install.
Audit. Before committing significant work, run /userspice-audit on the changed files: /userspice-audit usersc/contact.php. Single-file mode is fast and prints inline findings.
Scan. Before deploying, run the Security Scanner against the project for the mechanical-pattern catches the audit skill doesn't model.

Steps 1–4 happen continuously during development. Step 5 happens at deploy gates. Together they make up the difference between "AI wrote it" and "this is going to production."

Troubleshooting

"The skills don't show up when I type /." Restart Claude Code — skills are read on startup. Verify the folders exist: ls ~/.claude/skills/ should list the three directories. Each must contain a SKILL.md file.

"The audit ran but didn't find my UserSpice install." The skill walks up from the current directory looking for users/init.php. You probably ran claude from outside the project. cd in first, then start Claude.

"Claude doesn't seem to read CLAUDE.md." Confirm the file is at the project root, named exactly CLAUDE.md (case-sensitive on Linux). Start a fresh session — long-running sessions don't re-read it.

"Find / grep still prompts after I added the allowlist." Check JSON syntax with cat ~/.claude/settings.json | python3 -m json.tool. A trailing comma or missing brace silently breaks the file. Restart Claude after editing settings.

"The audit complained about my UserSpice version." The skills target 6.0.9+. Older versions may have different helper signatures. You can override the floor with the environment variable MIN_USERSPICE_VER=5.9.0 if you accept the caveat that some findings may misfire.

Rolling this out to a team

A few extra notes when you're setting this up for more than one developer:

Check CLAUDE.md into git. Every team member's Claude session benefits, not just the person who wrote it.
Project-level settings.json (instead of global). Commit .claude/settings.json at the project root so the Bash allowlist is shared. Add .claude/ to .gitignore's exceptions if your tooling auto-ignores dotfiles.
One person writes the project conventions. The first developer to set up writes the project-specific section of CLAUDE.md (permission IDs, internal API quirks, custom table naming). Everyone else inherits.
Code review the CLAUDE.md. The same way you'd review a style guide — wrong instructions in there propagate to every future PR.

Want help rolling this out?

We can install the toolkit across your team's machines, customize the CLAUDE.md for your project's conventions, walk a real PR through the workflow, and answer the "but what about…" questions as they come up. Send a note below.