Customization

What surchin init Installs

When you run npx @surchin/surchin init, Surchin adds a ## Surchin Knowledge Base section to your project's CLAUDE.md. This section instructs AI agents how to interact with the knowledge substrate throughout their workflow.

The installed template:

• Defines mandatory rules requiring all agents (including sub-agents) to query and deposit knowledge
• Configures the query-explore-deposit loop — a six-step workflow agents follow on every task
• Includes parameter guidance for file paths, tags, symbols, and error text so agents pass the right context to each tool call
• Provides deposit heuristics that help agents decide what knowledge is worth capturing

Managed Blocks

Surchin uses marker comments to manage its section of your CLAUDE.md:

<!-- SURCHIN:START -->
## Surchin Knowledge Base
... managed content ...
<!-- SURCHIN:END -->

• Don't edit inside the markers — changes between SURCHIN:START and SURCHIN:END will be overwritten when you update
• Add custom instructions outside the block — anything above or below the markers is yours to customize freely
• Update with surchin update — refreshes the managed section to the latest version while preserving your customizations

Customization Tips

The installed template works well out of the box, but you can tailor it to your team's needs by adding instructions outside the managed block:

• Deposit behavior

  Adjust when agents deposit — more aggressive for exploratory phases where you want to capture every finding, more conservative for stable code where noise should be minimized.

• Tag conventions

  Define team-specific tags so agents use consistent categorization. For example, standardize on payments, stripe for billing-related knowledge, or auth, oauth for authentication.

• Query frequency

  Configure how often agents query the substrate. Increase for unfamiliar or rapidly-changing code; reduce for well-documented, stable areas where queries add latency without much benefit.

• Team conventions

  Add project-specific rules like “always deposit after modifying migration files” or “tag all auth-related deposits with security.”

Advanced Examples

Add these sections to your CLAUDE.md outside the managed block to customize agent behavior:

Tag conventions

Define a taxonomy so all agents use consistent tags across sessions and team members:

### Tag Conventions
- Infrastructure: `infra`, `docker`, `ci`
- Frontend: `ui`, `react`, `styles`
- Backend: `api`, `db`, `auth`

Project-specific deposit rules

Override the default deposit heuristics with rules specific to your project:

### Deposit Rules
- Always deposit after modifying database migrations
- Deposit PITFALL when a test fails for non-obvious reasons
- Tag all auth-related deposits with `security`