[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.Prerequisites: MUST ATTENTION READ before executing:
Scan & Update Reference Doc — Surgical updates only, never full rewrite. 1. Read existing doc first — understand current structure and manual annotations 2. Detect mode: Placeholder (only headings, no content) → Init mode. Has content → Sync mode. 3. Scan codebase for current state (grep/glob for patterns, counts, file paths) 4. Diff findings vs doc content — identify stale sections only 5. Update ONLY sections where code diverged from doc. Preserve manual annotations. 6. Update metadata (date, counts, version) in frontmatter or header 7. NEVER rewrite entire doc. NEVER remove sections without evidence they're obsolete.
Output Quality — Token efficiency without sacrificing quality. 1. No inventories/counts — AI cangrep | wc -l. Counts go stale instantly 2. No directory trees — AI canglob/ls. Use 1-line path conventions 3. No TOCs — AI reads linearly. TOC wastes tokens 4. No examples that repeat what rules say — one example only if non-obvious 5. Lead with answer, not reasoning. Skip filler words and preamble 6. Sacrifice grammar for concision in reports 7. Unresolved questions at end, if any
Quick Summary
Goal: Scan backend codebase and populate docs/project-reference/backend-patterns-reference.md with actual repository patterns, CQRS command/query structures, validation patterns, entity conventions, event handlers, and migration approaches. (content auto-injected by hook — check for [Injected:...] header before reading)
Workflow:
- Read — Load current target doc, detect init vs sync mode
- Scan — Discover backend patterns via parallel sub-agents
- Report — Write findings to external report file
- Generate — Build/update reference doc from report
- Verify — Validate code examples reference real files
Key Rules:
- Generic — works with any backend framework (.NET, Node.js, Java, etc.)
- Detect framework first, then scan for framework-specific patterns
- Every code example must come from actual project files with file:line references
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
Scan Backend Patterns
Phase 0: Read & Assess
- Read
docs/project-reference/backend-patterns-reference.md - Detect mode: init (placeholder) or sync (populated)
- If sync: extract existing sections and note what's already well-documented
Phase 1: Plan Scan Strategy
Detect backend framework:
.csprojfiles →.NET (check for MediatR, CQRS patterns)package.jsonwith express/fastify/nestjs → Node.jspom.xml/build.gradle→ Java/Kotlinrequirements.txt/pyproject.toml→ Python
Use docs/project-config.json contextGroups/modules if available for service paths.
Phase 2: Execute Scan (Parallel Sub-Agents)
Launch 3 Explore agents in parallel:
Agent 1: Repository & Entity Patterns
- Grep for repository interfaces (
interface I*Repository,extends Repository) - Find entity/model classes (base class inheritance, attributes/annotations)
- Find DTO classes and mapping patterns (AutoMapper, manual mapping,
MapTo*methods) - Discover data access patterns (Unit of Work, DbContext, MongoDB collections)
- Look for extension methods on repositories
Agent 2: CQRS & Command/Query Patterns
- Grep for command handlers (
IRequestHandler,CommandHandler,@CommandHandler) - Grep for query handlers, query objects
- Find validation patterns (FluentValidation, class-level validators, middleware)
- Discover request/response wrapper patterns (Result, ApiResponse)
- Find authorization attributes/decorators on handlers
Agent 3: Events, Migrations & Infrastructure
- Grep for event handlers, domain events, integration events
- Find message bus consumers/publishers (MassTransit, RabbitMQ, Kafka patterns)
- Discover migration patterns (EF migrations, Flyway, custom migrators)
- Find background job patterns (Hangfire, Quartz, hosted services)
- Grep for middleware, filters, interceptors
Write all findings to: plans/reports/scan-backend-patterns-{YYMMDD}-{HHMM}-report.md
Phase 3: Analyze & Generate
Read the report. Build these sections:
Target Sections
| Section | Content |
|---|---|
| Repository Pattern | Interface naming, base classes, service-specific repos, extension methods with examples |
| CQRS Patterns | Command structure, query structure, handler patterns, file organization conventions |
| Validation Patterns | Validation approach (fluent API, attributes, etc.), common rules, error response format |
| Entity Patterns | Base classes, property conventions, factory methods, domain logic placement |
| DTO Mapping | Mapping approach, who owns mapping (DTO, handler, or service), examples |
| Event Handlers | Domain events vs integration events, handler discovery, side-effect placement |
| Message Bus | Cross-service communication patterns, consumer conventions, message contracts |
| Migrations | Migration strategy, naming conventions, data migration patterns |
| Background Jobs | Job scheduling, recurring jobs, one-time jobs, conventions |
| Authorization | Auth patterns, permission checks, role-based access |
Content Rules
- Show actual code snippets (5-15 lines) from the project with
file:linereferences - Include "DO" and "DON'T" examples where anti-patterns are clear
- Use tables for convention summaries (naming, file locations, base classes)
- Group patterns by concern, not by framework feature
Phase 4: Write & Verify
- Write updated doc with
<!-- Last scanned: YYYY-MM-DD -->at top - Verify: 5 code example file paths exist (Glob check)
- Verify: class names in examples match actual class definitions
- Report: sections updated, patterns discovered, coverage gaps
Closing Reminders
- IMPORTANT MUST ATTENTION break work into small todo tasks using
TaskCreateBEFORE starting - IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
- IMPORTANT MUST ATTENTION cite
file:lineevidence for every claim (confidence >80% to act) - IMPORTANT MUST ATTENTION add a final review todo task to verify work quality
- IMPORTANT MUST ATTENTION read existing doc first, scan codebase, diff, surgical update only. Never rewrite entire doc.
- IMPORTANT MUST ATTENTION follow output quality rules: no counts/trees/TOCs, rules > descriptions, 1 example per pattern, primacy-recency anchoring.