From bb331fc489a12472b42d3560306445deda155e27 Mon Sep 17 00:00:00 2001 From: Abhinav Gautam Date: Thu, 26 Mar 2026 18:59:00 +0530 Subject: [PATCH] add Claude Code support alongside Codex - Create CLAUDE.md with project instructions, bootstrap commands, and rules - Make AGENTS.md agent-agnostic (Codex, Claude Code, Cursor, etc.) - Add Claude Code workflow section to docs/WORKFLOW.md - Update docs/ARCHITECTURE.md to reference CLAUDE.md and all agents Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 3 +- CLAUDE.md | 95 ++++++++++++++++++++++++++++++++++++++++++++ docs/ARCHITECTURE.md | 7 ++-- docs/WORKFLOW.md | 12 ++++++ 4 files changed, 113 insertions(+), 4 deletions(-) create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index c889147..2e94ae4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This repository is a Node.js backend template maintained for human developers and Codex. +This repository is a Node.js backend template maintained for human developers and AI coding agents (Codex, Claude Code, Cursor, and others). ## Read this first @@ -45,6 +45,7 @@ A task is complete only when: - Active execution plans: `docs/exec-plans/active/` - Completed execution plans: `docs/exec-plans/completed/` - Codex project config: `.codex/` +- Claude Code project config: `CLAUDE.md` - Database migrations: `migrations/` - Worktree/bootstrap helpers: `scripts/` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..010041f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,95 @@ +# CLAUDE.md + +Project instructions for Claude Code. Read this before making any changes. + +## What this is + +A Node.js backend template with a harness-engineering overlay for AI coding agents. See `AGENTS.md` for the full operational contract. + +## Bootstrap + +```sh +npm ci || npm install +npm run worktree:bootstrap # if working in a worktree +npm run dev:stack:up # when you need DB, Redis, or observability +``` + +## Verify before declaring done + +```sh +npm run verify +``` + +This runs: lint, format check, architecture inventory, docs validation, quality score, tests, and smoke tests. + +## Key commands + +| Task | Command | +| ----------------- | ---------------------------------------- | +| Start dev server | `npm run start:dev` | +| Run tests | `npm run test` | +| Smoke test | `npm run test:smoke` | +| Lint + fix | `npm run lint:fix` | +| Format | `npm run format` | +| New migration | `npm run migration:new -- --name=` | +| Run migrations | `npm run migrate` | +| Migration status | `npm run migrate:status` | +| Check plan claims | `npm run claim:check` | +| Start local stack | `npm run dev:stack:up` | +| Stop local stack | `npm run dev:stack:down` | +| Quality score | `npm run quality:score` | + +## Project structure + +``` +bin/www → entry point (clustering) +init.js → master process init (DB bootstrap, cron) +app.js → Express app setup +config/ → DB, env loading, migrations, startup guard +models/ → Sequelize models +migrations/ → Umzug schema migrations +middleware/ → auth, validation, rate limiting, errors +routes/v1/ → versioned API routes +controllers/v1/ → request handlers +service/v1/ → business logic + workflow engine +helper/ → auth, casbin, cron, mail, SMS, PDF, uploads +utils/ → constants, formatters, pagination, time +scripts/ → bootstrap, verification, plan helpers +docs/ → architecture, workflow, quality, security docs +``` + +## Request flow + +``` +bin/www → init.js → app.js → middleware → routes → controllers → services → models → DB +``` + +## Rules + +- Read files before changing them. +- Keep changes small and verifiable. +- Extend existing patterns — don't create parallel ones. +- Use the existing bootstrap/startup flow (`bin/www` → `init.js` → `app.js`). +- Use the built-in Umzug migration system for schema changes. Don't add alternate migration tools. +- Use canonical integrations (see `AGENTS.md`) — don't introduce parallel libraries for uploads, SMS, mail, PDF, or pagination. +- Don't delete template features unless explicitly asked. +- Update docs when architecture or behavior changes. +- For multi-agent work: check `docs/exec-plans/active/`, run `npm run claim:check`, respect existing claims. + +## Environment + +- `.env.development` — default local config +- `.env.worktree` — worktree-specific overrides (auto-generated by bootstrap) +- `.env.local` — personal overrides (gitignored) +- Priority: `.env.local` > `.env.worktree` > `.env.{NODE_ENV}` + +## DB safety + +- `init.js` guards DB bootstrap — only runs against worktree-local DB unless `ALLOW_NON_LOCAL_STARTUP_DB_BOOTSTRAP=true`. +- Use `SKIP_STARTUP_MIGRATIONS=true` for local tasks that don't need DB. + +## Testing + +- Framework: Mocha + Supertest +- Test files: `test/**/*.test.js` +- Always run `npm run test` before committing. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c1e4bd0..69f26f9 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -10,9 +10,10 @@ Process bootstrap -> Environment loading -> Optional instrumentation -> Request ## Harness-engineering overlay -The repository also includes a repo-native operating layer designed for Codex and other coding agents: +The repository also includes a repo-native operating layer designed for AI coding agents (Codex, Claude Code, and others): -- `AGENTS.md`: short operational contract for agents. +- `AGENTS.md`: short operational contract for all agents. +- `CLAUDE.md`: project instructions for Claude Code. - `docs/`: versioned system of record for architecture, workflow, quality, reliability, and security. - `docs/MIGRATIONS.md`: canonical schema-change workflow for downstream projects. - `docs/OBSERVABILITY.md`: local logs, metrics, traces, and query workflows. @@ -37,4 +38,4 @@ Application code and repo operations are separate concerns: - Stateful business workflows can be implemented in `service/v1/` with Sequelize models backing assignment, workflow action, and escalation rules. - Agent operating guidance lives in repo-root docs and scripts. -This keeps the backend template usable for normal development while making the repository legible to Codex. +This keeps the backend template usable for normal development while making the repository legible to AI coding agents. diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md index bf7d407..7f42702 100644 --- a/docs/WORKFLOW.md +++ b/docs/WORKFLOW.md @@ -23,6 +23,18 @@ 9. Use `npm run migration:new -- --name=` for schema changes. Master startup bootstraps models and applies pending migrations through the built-in migrator only when the DB target matches the expected worktree-local stack or `ALLOW_NON_LOCAL_STARTUP_DB_BOOTSTRAP=true` is set for an intentional deployment-style environment. For local non-DB tasks, agents may temporarily use `SKIP_STARTUP_MIGRATIONS=true` to bypass the startup bootstrap path. Do not add a second migration tool or alternate startup path. 10. Run `npm run verify` before review or merge. +## Claude Code workflow + +1. Open the repo directory in Claude Code (`claude` CLI). +2. Claude Code reads `CLAUDE.md` automatically for project-specific instructions. +3. For isolated work, use Claude Code's built-in worktree support or create one manually. +4. Run `npm run worktree:bootstrap` in each new worktree. +5. Use `npm run dev:stack:up` when the task needs local DB, Redis, or observability services. +6. Run `npm run claim:check` and use active execution plans in `docs/exec-plans/active/` for medium or large tasks. Respect any existing claim that overlaps your intended scope. +7. Use `npm run migration:new -- --name=` for schema changes. The same DB guard and migration rules from the Codex workflow apply. +8. Run `npm run verify` before declaring work done. +9. Use `/commit` to commit changes following project conventions. + ## Worktree workflow ```sh