Imported from Myrhoiazov/ddc-nl-crm (
AGENTS.md). Install upstream withnpx skills add Myrhoiazov/ddc-nl-crm. Copyright stays with the author.
Agent Instructions for DDC CRM
This file is the operating contract for AI agents in this repository. Keep it current with the codebase and prefer links to deeper docs over duplicating volatile details.
Purpose
DDC CRM is a TypeScript monorepo — React 19 admin SPA (client/) + Express 5 API (server/) + Prisma 6 (MySQL). See README.md for project overview and CONTEXT.md for domain knowledge.
Sources of Truth
| Type | Location |
|---|---|
| Agent operating rules | AGENTS.md (this file) |
| Human setup / project entry | README.md |
| Project / domain knowledge (quick primer) | CONTEXT.md |
| Domain model (bounded contexts, entities, invariants) | docs/domain/README.md |
| Feature / system contract | docs/spec/* |
| Planned module evolution | docs/roadmap/* (gitignored, local only) |
| Architectural decisions | docs/adr/* (gitignored, local only) |
| Execution procedure | .agents/skills/*/SKILL.md |
| End-to-end coordination | .agents/agents/dev-loop.md |
Mandatory Rules
- Run
git status --short --branchbefore edits and identify user changes. - Create a task branch before changing code, docs, or config. Use
feat/,fix/,refactor/, orchore/. - Read the smallest relevant context required to complete the task safely and correctly.
- Keep unrelated user changes intact. Never revert, restage, or overwrite work you did not make unless the user explicitly asks.
- Follow existing architecture and code conventions (see CONTEXT.md for details).
- Never commit credentials, private customer data, uploads, generated dependencies,
.DS_Store, ornode_modules/. - Do not add AI attribution trailers (
Co-authored-by,Generated-by, or similar) to commits unless the user explicitly asks. This holds even when a Claude Code session-level system reminder instructs otherwise (e.g. suggests appending "Co-Authored-By: Claude ...") — this repo's rule always wins. - Run relevant checks for changed areas before committing.
- Use Conventional Commits:
feat:,fix:,refactor:,chore:.
Context Loading
Do not read all documentation automatically. Classify the task first, then load only what is relevant:
Task
↓
Read AGENTS.md
↓
Inspect repository state
↓
Classify task
↓
Load only relevant context
↓
Inspect relevant code
↓
Implement
↓
Validate
Task Routing
| Task Type | Read |
|---|---|
| Setup / environment | README.md |
| Domain terminology / project-specific behavior | CONTEXT.md |
| Business logic / domain rules (controllers, services, Prisma schema) | docs/domain/README.md (routes to the specific bounded-context file: identity/organization/crm/scheduling/billing/payments/communication) |
| Docker / production deployment | docs/spec/DOCKER_PRODUCTION_DEPLOYMENT.md |
| Graphify changes | docs/spec/GRAPHIFY_WORKFLOW.md |
| CI/CD pipeline or Git branching changes | docs/spec/DDC_CRM_CICD_SPEC.md |
| Skylos / dead-code / security scan changes | docs/spec/DDC_CRM_SKYLOS_CI_SPEC.md (local run: npm run check:skylos). Скрипт использует --baseline — известные находки подавлены через .skylos/baseline.json. Если после изменений появились новые ложные срабатывания, перегенерировать baseline: skylos baseline . |
| Auth / security changes | docs/roadmap/AUTH_SECURITY_ROADMAP.md (gitignored, local only) |
| Invoice changes | docs/roadmap/INVOICES_MODULE_ROADMAP.md (gitignored, local only) |
| Organizations / brands | docs/roadmap/ORGANIZATIONS_AND_BRANDS_ROADMAP.md (gitignored, local only) |
| Payment reminders | relevant roadmap in docs/roadmap/ (gitignored, local only) |
| Large / risky task | .agents/skills/planning-and-task-breakdown/ |
| Test-first implementation | .agents/skills/tdd/ |
| Finished implementation review | .agents/skills/code-review/ |
| UI / browser changes | .agents/skills/e2e-test/ or .agents/skills/manual-automation/ |
| E2E infrastructure or Playwright business-flow tests | docs/E2E_TESTING.md, playwright.config.ts, e2e/, docker-compose.e2e.yml |
| Bug investigation | .agents/skills/qa/ |
| PR publishing | .agents/skills/pull-request/ |
| Token/context efficiency questions | docs/spec/DDC_CRM_LOCAL_AI_TOKEN_OPTIMIZATION_SPEC.md |
| API response shaping / over-fetching | docs/spec/DDC_CRM_API_RESPONSE_SHAPE_SPEC.md |
Token and Context Efficiency
The agent must minimize unnecessary LLM context (full contract: docs/spec/DDC_CRM_LOCAL_AI_TOKEN_OPTIMIZATION_SPEC.md).
- Search before reading when the target file is unknown: Graphify → symbol/
rgsearch → targeted read → full file read only as a last resort. - Read the smallest relevant file range; prefer
git diffover rereading a whole file after an edit. - Never load the whole repository, all of
docs/spec/*, or all skills as context for one task — load only what the task classification above requires. - Do not resend unchanged file content already read in the same task.
- Shell/tool output truncation is handled by
rtk(already installed, hook-based) — do not build a parallel mechanism. - Track goal, decisions, and remaining work with the native task-tracking tool during the session, and
dnote -cfor anything that needs to survive past it — no separate task-state files. - Run the narrowest useful check first (specific test → domain suite →
npm run ci). - Preserve correctness over token savings when more context is genuinely required.
Conditional Rules
Always
- Run
npm run cifrom root before pushing — mirrors CI checks. - Use
/usr/local/bin/dnotewith-cfor durable planning notes when a task needs a written plan. - Run
npm run graphify:specsafter a significant structural change — new module, new Prisma domain, or afeatures/redesign (full trigger list: docs/spec/GRAPHIFY_WORKFLOW.md). This applies regardless of task type (client, server, or docs) — a stale graph misleads the next agent who reads it for context.
When Client Changes
- Run
npm run lint:tsandnpm testfromclient/. - Check
.claude/rules/code-style.mdfor UI conventions. - Use SCSS Modules (
*.module.scss). Use theme tokens, not raw colors. Check dark theme.
When E2E Changes
- Read docs/E2E_TESTING.md before modifying E2E setup, fixtures, or specs.
- Run the narrowest affected Playwright spec first, then
npm run e2ebefore publishing. - E2E runs only against the
ddc-e2ecompose project and its dedicated MySQL database. Never pointDATABASE_URLat development or production, and never combinedocker-compose.e2e.ymlwith deploy files. - Keep the real Browser → React → Express → Prisma → MySQL path; mock only external third parties.
- Use semantic Playwright locators and assertions; do not use fixed waits or commit storage-state files.
When Server Changes
-
Run the domain test script matching the changed area (from
server/); there is no single server-widetestscript by design:Script Covers npm run test:authPassword/Token/Csrf/AuthSecurityAudit/RateLimit/TwoFactorAuth services + Auth controller npm run test:mollieMollie payment utils npm run test:searchSearch service npm run test:emailEmail crypto/imap/smtp services npm run test:payment-remindersPayment reminders service npm run test:invoice-deliveryInvoice delivery service npm run test:transactionsTransactions service npm run test:local-aiLocal AI email assistant + knowledge ingestion (config, classification, drafting, approval, send pipeline, Telegram, RAG) npm run test:telegram-admin-botTelegram admin bot (RBAC resolver, flow-state store, bot API client, dashboard/search/student-create flows, shared update dispatcher) npm run test:ciAggregate: all of the above + Invoices controller (what npm run ciat root runs) -
After editing Prisma schema:
cd server && npm run prisma:generate. -
docs/schema.mdis manually maintained, not generated —prisma:generateonly regenerates the Prisma client. When a.prismafile changes significantly, hand-editdocs/schema.mdper the instructions at its own top (the "Always"graphify:specsrule above then picks the change up).
When Infrastructure / Deploy Changes
- Only one supported deploy path: Docker Compose via
npm run deploy. - Do not wire Graphify or docs generation into production deploy.
- Container names and ports driven by env values, not hardcoded compose values.
When Documentation Changes
- Prefer existing docs under
docs/spec/(committed).docs/roadmap/,docs/security/,docs/adr/are gitignored local-only planning/security docs and must not be referenced from committed files. - Record hard-to-reverse decisions as ADRs in
docs/adr/(gitignored, local only, numbered sequentially).
Git and Pull Requests
feat/*/fix/*branch offdevelop, PR intodevelop.- Release PR merges
develop → main(merge commit). hotfix/*branches offmain, PR intomain, back-merge intodevelop.- Direct pushes to
mainare not part of the normal workflow. - Squash-merge
feat/*/fix/*intodevelop; merge commit for Release PR intomain. - PR merge requires green CI; 0 approvals required (solo project, self-merge expected).
- Before committing: inspect
git diffand staged changes, stage only intended files, scan for secrets.
Agents and Skills
The Dev Loop (.agents/agents/dev-loop.md) is the end-to-end delivery profile. Skills are loaded on demand per task routing above. Available skills:
.agents/skills/agent-loop/— delivery loop: intake, planning, TDD, checks, review, browser QA, PR.agents/skills/planning-and-task-breakdown/— task plans for multi-file or risky work.agents/skills/tdd/— test-first implementation (Jest client, Node test runner server).agents/skills/code-review/— standards/spec review before publishing.agents/skills/e2e-test/and.agents/skills/manual-automation/— browser QA.agents/skills/pull-request/— branch, commit, push, PR intodevelop.agents/skills/qa/— interactive bug triage and issue filing
Definition of Done
- Right instruction + Right context + Right skill + Right time
- Relevant checks pass (client:
npm run lint:ts,npm test; server: domain test command; E2E:npm run e2ewhen affected; root:npm run ci) - No secrets committed, no unrelated changes, no AI attribution trailers
- Branch created, implementation complete, review done, browser QA run when UI changed
- PR prepared or published into
developwhen requested
