Skip to main content

AI Agent Coordination Guide

This document explains how AI coding assistants are configured in this repo and how to avoid conflicts when using multiple tools simultaneously.

The Problem​

When two AI tools (e.g. GitHub Copilot + Gemini) edit the same codebase independently, they can:

  • Generate conflicting field names (e.g. one uses url, another uses cdnUrl)
  • Use different enum casing (ACTIVE vs active)
  • Make incompatible architectural decisions
  • Introduce circular dependencies the other tool doesn't know about
  • Upgrade packages the other tool's assumptions depend on

The Solution: Single Source of Truth​

All AI tools in this repo are pointed at the same contract files:

FileRead byPurpose
AGENTS.mdGemini CLI, Claude Code, Cursor, any tool that reads root filesFull contract: conventions, field names, module patterns, forbidden patterns
.github/copilot-instructions.mdGitHub Copilot (in-editor)Summary of the same contract, Copilot-specific format

Both files say the same things. If you update one, update the other.

Which Tool to Use for What​

TaskPreferred ToolReason
Generate new NestJS module (boilerplate)EitherBoth understand NestJS patterns. Check AGENTS.md first.
Prisma schema changesCarefully in one tool onlyRun prisma migrate dev and prisma generate after any change before switching tools.
New API endpointOne tool per featureAvoid two tools editing the same controller simultaneously.
Frontend pages / componentsEitherWeb is well-isolated. Less risk of conflict.
TypeScript type errorsEitherBoth can read the Prisma schema.
Architecture decisionsRead apps/docs/docs/staff/ docs firstNever let an AI make structural decisions without human review.

Workflow to Avoid Conflicts​

Before starting a session with any AI tool:​

  1. git status — confirm clean working tree
  2. git pull — pull latest
  3. Run npx tsc --noEmit in apps/api and apps/worker — confirm zero errors before you start

During a session:​

  • Work on one feature/file set at a time
  • Do not let two tools edit the same module simultaneously
  • After any tool makes changes: commit or stash before switching tools

After a session:​

  • npx tsc --noEmit in every changed app
  • Review diffs for field names and enum values before committing
  • Commit with a message that names which tool made the change (optional but helpful for blame)

Current Known Gotchas (learned from experience)​

These are bugs that have been introduced and fixed — every AI must know them:

GotchaCorrect
ImageFile.url→ ImageFile.cdnUrl
ImageFile.sizeBytes→ ImageFile.fileSizeBytes (and it's BigInt)
ImageFile.exifDataField does not exist — EXIF goes on the Image model or is discarded
Location.lat / .lng→ Location.latitude / .longitude
User.displayNameField removed — use firstName + lastName
ImageStatus.PENDING_REVIEW→ ImageStatus.pending_review
Role.ADMIN→ Role.admin
user.sub→ user.id (JWT strategy returns { id, email, role })
IMAGE_PROCESS_QUEUE from queue.module.ts→ import from queue.constants.ts
BullModule.forRoot() in QueueModule with @Global()→ forRoot stays in AppModule
experimental.typedRoutes in next.config→ top-level typedRoutes: true
middleware.ts in Next.js 16+→ rename to proxy.ts, export proxy function
Storage backend hard-coded to R2→ use runtime storage config and StorageService
Photoshoot location without coordinates→ use upload-style address lookup/geocoding path
Automatic payout on photoshoot completion→ credit wallet only; payouts are explicit requests

Architecture Docs Reference​

Before making structural changes, read the relevant doc:

TopicDoc
What is in / out of MVPapps/docs/docs/staff/01-mvp-scope.md
System overviewapps/docs/docs/staff/02-architecture-overview.md
All tech choices with rationaleapps/docs/docs/staff/03-tech-stack.md
Directory layoutapps/docs/docs/staff/04-monorepo-structure.md
Database schemaapps/docs/docs/staff/05-database-schema.md
REST endpointsapps/docs/docs/staff/06-api-modules.md
Upload & storage pipelineapps/docs/docs/staff/07-storage-upload-pipeline.md
Search & mapapps/docs/docs/staff/08-search-and-map.md
Auth & RBACapps/docs/docs/staff/09-auth-and-authz.md
Admin portalapps/docs/docs/staff/10-admin-features.md
CI/CDapps/docs/docs/staff/11-cicd-deployment.md
Phase roadmapapps/docs/docs/staff/12-roadmap.md