AI tooling

NexSchool ships its AI configuration in the repo: the .claude/ directory drives how Claude Code plans, builds, reviews, and remembers work on this codebase.

What lives in `.claude/`

Claude Code is Anthropic’s terminal-based coding assistant. It reads the project files, runs commands, edits code, and loads the specialized configuration below. Everything an agent needs to work the NexSchool way is checked into .claude/:

.claude/
├── CLAUDE.md            Main config — loaded every session
├── PROMPT_GUIDE.md      Copy-paste prompts per role
├── SUBAGENT-GUIDE.md    Sub-agent instructions
├── README.md            Quick reference
├── settings.json        Hooks + tool config (project)
├── rules/               Always-on coding rules
├── roles/               Agent role definitions
├── flows/               Ordered pipeline (feature_flow.md)
├── skills/              Specialized skill files (SKILL.md per skill)
├── memory/              Persistent architecture + module context
├── commands/            Custom slash commands
└── hooks/               Shell hooks fired around tool calls

CLAUDE.md is loaded automatically at the start of every session and is the entry point that points at the rest.

Rules

Every file in .claude/rules/ is always-on — applied to every response without being asked for. Apply them silently; don’t restate their contents in chat.

Rule file	Enforces
`api-conventions.md`	URL structure, HTTP methods, response envelope, pagination, dates
`coding-standards.md`	Function size, naming, file organization, type safety
`database-conventions.md`	Naming, required columns, types, nullability, indexes, soft deletes
`error-handling.md`	Error hierarchy, catch behavior, retry strategy
`forbidden-patterns.md`	Banned patterns: `eval`, `SELECT *`, N+1 queries, magic numbers
`git-conventions.md`	Branch naming `type/TICKET-desc`, commits `type(scope): desc`
`logging-standards.md`	Log levels, structured logging, what to / not to log
`naming-conventions.md`	camelCase / PascalCase / snake_case by context
`planner.md`	When to write a plan, and the plan format
`prompt-efficiency.md`	Diff-first responses, no full-file rewrites unless needed
`query-conventions.md`	Tenant-scoped TanStack Query keys and `enabled` gating
`security-guardrails.md`	No hardcoded secrets, parameterized queries, bcrypt, CORS
`team-workflow.md`	Which AI role to use when
`testing-conventions.md`	Test structure, naming, what to test, mocking rules

Roles & skills (the pipeline)

Roles are the personas an agent adopts for a stage of work; each role loads one or more skills (a SKILL.md with focused instructions). Role definitions live in .claude/roles/, skills in .claude/skills/<area>/<name>/SKILL.md, and the ordered sequence in .claude/flows/feature_flow.md.

The four feature-pipeline roles run in order:

Stage	Role	Loads skill	Trigger
1	`system_designer`	`product/product-owner` (+ planner)	New requirement, architecture / API / DB design
2	`designer`	`design/ui-ux-designer`	A new UI screen, flow, or component is needed
3	`fullstack_engineer`	`engineering/feature-developer`	After planning (and design), ready to implement
4	`reviewer`	`qa/qa-engineer` (also `code-reviewer`, `security-reviewer`)	After implementation, before PR

The workflow from .claude/rules/team-workflow.md:

[new feature / requirement]
  → system_designer   (plan: scope, steps, risks)
  → designer          (UI/UX — skip for backend-only)
  → fullstack_engineer (implementation)
  → reviewer          (QA + security on the delta)
  → dogfooding-as-end-user  (mandatory end-user pass)
  → wrap-feature      (post-build hygiene)

Notes worth knowing:

Stage 2 is skipped for backend-only, migration, config, or API-only work.
The designer role must get user approval on canvas mockups before code.
The reviewer scope is the changed files plus their direct callers.
dogfooding-as-end-user is mandatory after any behavioral/user-facing change, whether or not it was asked for — walk the feature as a real user across personas.

Beyond the four pipeline roles, .claude/skills/ holds additional skills grouped by area — for example engineering/ (code-explorer, debugging-assistant, test-generator, pr-description-writer), architecture/ (api-design-reviewer, database-schema-reviewer), devops/ (deployment-debugger, incident-postmortem, migration-planner), security/security-reviewer, product/, qa/, ai/, delivery/, plus graphify and dogfooding-as-end-user.

Memory

.claude/memory/ gives Claude persistent context across conversations. Prefer it over raw repo scans — the files are compressed summaries with file anchors, so they cost far less context than reading source.

.claude/memory/architecture.md — high-level reference: layer overview (HTTP, data, authZ, clients), monorepo paths, ERP domains.
.claude/memory/modules/*.md — per-domain summaries:

File	Covers
`academics_schedule.md`	Academic years, terms, timetable, schedule, holidays
`attendance.md`	Attendance APIs and models
`auth_platform.md`	Auth, JWT, tenant resolution, platform module
`finance_fees.md`	Finance, fees, invoices, payments
`operations_subscription.md`	Subscriptions, operations
`people_classes.md`	Students, teachers, classes
`rbac_users.md`	RBAC, roles, permissions, users
`school_structure.md`	School units, grades, programmes

Session bootstrap (load once per reset, don’t reload mid-session unless context was cleared):

CLAUDE.md (auto-loaded)
.claude/memory/architecture.md
The relevant .claude/memory/modules/<area>.md for the current task

Commands

Custom slash commands in .claude/commands/ are shortcuts into the roles above:

Command	Loads	When to use
`/system-designer`	`system_designer` role	Plan a new feature
`/designer`	`designer` role	Design UI
`/fullstack-engineer`	`fullstack_engineer` role	Implement a feature
`/reviewer`	`reviewer` role	Review code
`/feature-flow`	Pipeline reminder	Run the full pipeline

Copy-paste prompts for each role also live in .claude/PROMPT_GUIDE.md; plain-text Role: lines work anywhere. The commands are mirrored for Cursor under .cursor/commands/ (same filenames, plus that IDE’s speckit.* set), so the same roles are reachable from Cursor.

Hooks

.claude/settings.json wires shell hooks around tool calls:

PreToolUse (Bash) — if graphify-out/graph.json exists, injects a reminder to read graphify-out/GRAPH_REPORT.md before searching raw files.
PostToolUse (Edit|Write) — runs .claude/hooks/docs-reminder.sh, which maps the edited path to the matching docs-new/ file and reminds you to keep that doc current.

docs-reminder.sh reads the edited file path from stdin and maps source paths to docs. For example server/modules/students/ maps to docs-new/11-module-students.md, admin-web/ to docs-new/20-admin-web.md, and server/app.py or server/core/ to docs-new/07-backend.md. Edits inside docs-new/, .claude/hooks/, or .claude/settings are skipped.

Graphify

Graphify turns the codebase (or any folder) into a knowledge graph for fast exploration. It is a skill (.claude/skills/graphify/SKILL.md), not a slash command — /graphify does not work in Claude Code.

Invoke it by saying “Run graphify on this folder” or “Build the knowledge graph for this project”.
Output lands in graphify-out/ — GRAPH_REPORT.md (god nodes, community structure) plus an HTML graph and JSON.
When graphify-out/ exists: read GRAPH_REPORT.md before broad exploration; after code changes run graphify update ..

Keeping docs current

After any edit that changes behavior, adds a route/model/column/config, or removes something, apply a minimal diff to the matching docs-new/ file — add, update, or remove only the affected section. Do not rewrite the whole doc, and do not touch docs for purely cosmetic changes (variable renames, comments, typo fixes). The PostToolUse hook above surfaces the right target file automatically after each Edit/Write. When a graph exists, run graphify update . after code changes so the knowledge graph stays in sync.

Adding a feature About ADRs