Last Updated: December 24, 2025 This document governs how AI assistants work on this codebase. The goal: AI-driven development that produces code a human can actually review.
This project is AI-driven, human-assisted. AI writes all code; humans review, provide feedback, and approve.
Collaboration over completion. It's better to check in early than to finish something wrong. Iteration is expected, not a sign of failure. When uncertain, ask.
- One logical change per session — a feature, a fix, a refactor. Not all three.
- Keep changes reviewable — target ~200 lines or less as a guideline.
- Scaffolding or boilerplate may exceed this; if so, provide a summary the human can use to review efficiently.
- If a task feels large, propose a breakdown first and get approval.
- Run tests before committing. If tests require infrastructure you don't have, say so and stop.
- Never commit code you haven't seen run.
- After completing work, summarize what was done and wait for feedback.
- If requirements are unclear, ask before implementing.
- If multiple approaches exist, present options rather than picking silently.
- If stuck, say so — with context on what you tried.
- Readable over clever. Optimize for human review.
- Explicit over implicit. No magic.
- Comments explain "why", not "what".
- Describe before building. Before writing code, describe what it should do in plain English. Wait for approval.
- Tests accompany code. Every feature includes tests. Tests are required before committing, not before coding.
- Tests verify requirements, not implementation. Write tests that catch unmet requirements, not tests that mirror code structure.
Follow Conventional Commits format:
<type>(<optional scope>): <description>
<optional body>
<optional footer>
Types:
feat— adds or removes a featurefix— fixes a bugrefactor— restructures code without changing behaviortest— adds or corrects testsdocs— documentation onlybuild— build system, dependencies, CI/CDchore— miscellaneous (last resort)
Rules:
- Use imperative mood: "add" not "added" or "adds"
- Don't capitalize the first letter
- No period at the end
- Keep the first line under 72 characters
Examples:
feat: add share endpoint for emailing observations
fix: handle PostgreSQL Date objects in fetch
test: add coverage for empty email array
docs: update API spec with new endpoints
refactor: extract sanitizeFilename to utils
- Small PRs — One feature or fix per PR
- Copilot review — Request review, triage feedback (valid vs noise), address valid points
- Separate commits for review feedback — Don't amend; add new commits addressing feedback
- Squash at merge — Keep main history clean
- No amending after push — Once pushed, commits are immutable (preserves review context)
Not all automated review comments are worth addressing. Valid feedback includes:
- Missing test coverage
- Actual bugs or edge cases
- Security concerns
Noise to skip (with justification):
- Style preferences already covered by existing patterns
- Suggestions that add complexity without clear benefit
- Comments on intentional design decisions (document why and move on)
- Tests live next to source —
foo.ts→foo.test.ts - Mock external services — Don't hit real APIs in tests
- Clean test output — Logger disabled in test mode (
NODE_ENV=test) - Integration tests use real DB — Test database, cleaned between runs
| Resource | Location |
|---|---|
| API Specification | docs/api-specification.md |
| Database Schema | docs/database-schema.md |
| Stack | Node.js, TypeScript, Fastify, PostgreSQL (raw SQL), Zod, Vitest |
| Hosting | Railway (API + PostgreSQL) |
| Resend |
This backend API is part of a three-repository system:
- Location:
../wbs-ethogram-form/ - Purpose: React application for data entry
- AI Guidance: wbs-ethogram-form/CLAUDE.md
- Quick Reference: wbs-ethogram-form/.github/copilot-instructions.md
- Location:
../ethogram-notes/ - Purpose: Project context, study feedback, improvement roadmap
- Overview: ethogram-notes/README.md
- Current Work: ethogram-notes/01-ACTIVE/24hr-study-feedback.md
When making changes that affect multiple repositories:
Behavior Changes (Items 5-9 in 24hr study feedback):
- Update
src/constants/behaviors.jsin frontend - Update
src/services/excel.tsBEHAVIOR_ROW_MAPPING in backend - Document in
ethogram-notes/01-ACTIVE/24hr-study-feedback.md - Coordinate deployment (both must go live together)
Data Shape Changes (Phase 4 multi-subject):
- Frontend state management refactor (see
ethogram-notes/data-shape-alignment-analysis.md) - Remove data transformation in
src/routes/observations.ts(backend already stores arrays) - Update Excel generation in both repos
Timezone Simplification (Item 11):
- Frontend only — no backend changes needed
- Backend already stores times as submitted
src/
app.ts — Fastify app builder
server.ts — Entry point
config.ts — Environment config (Zod validation)
db/ — Database connection pool and query helper
routes/ — Route handlers (one file per resource)
services/ — Business logic (email, excel generation)
utils/ — Shared utilities (rate limiting, sanitization)