DevEx.md - Measure the Loop, Not the Build

# DevEx.md - Developer Experience Guide
<!-- Onboarding, productivity, debugging workflows, team conventions -->
<!-- Everything a contributor - human or agent - needs to be effective from day one -->
<!-- Last updated: 2026-07-27 -->

## What Developer Experience Covers Now

Developer experience used to mean the time between a person deciding to make a change and that change being live. It still means that. But a repository now has two kinds of contributor, and both of them experience your setup:

- **People**, who need access, context, a working local environment, and someone to ask.
- **Agents**, which need the same things expressed differently: an instruction file they can actually work from, exact commands, credentialed tool access, and a fast way to prove a change is correct.

The overlap is almost total, and that is the useful insight. Every investment that shortens the loop for an agent - exact commands, a single verification entry point, a documented environment, a fast test suite - shortens it for the human too. The reverse is not always true: a tribal-knowledge shortcut that a senior engineer keeps in their head helps nobody else at all.

A blunt test for how good your repository's DX actually is: hand your context to a brand-new hire **or** to a fresh agent with no prior session, ask for a small real change, and measure the time to correct output. Anything they have to ask you is a gap in the repository, not a gap in them.

## Onboarding Checklist

### Before Day 1 (Manager / IT Handles)
- [ ] Source control organization access granted with the correct team membership
- [ ] Chat workspace invitation sent - join the engineering, team, deploys, and incidents channels
- [ ] Email and calendar access configured
- [ ] Secret manager vault access for development credentials
- [ ] Hardware ordered and shipped (if remote)
- [ ] Welcome doc sent with links to this guide and the team wiki
- [ ] Agent tooling access provisioned at the same time as everything else - a coding assistant they cannot log into on day one is a day of lost ramp

### Day 1: Access and Environment
- [ ] Complete the development environment setup (see `codev.md`)
- [ ] Clone the main repository and run the application locally
- [ ] Run `npm run verify` on a clean checkout - it should pass with zero edits
- [ ] Point your coding agent at the repository and ask it to summarize the architecture. If the summary is wrong, that is a documentation bug worth filing on day one - a fresh agent is the least biased reader your context file will ever get.
- [ ] Get added to the on-call rotation calendar (shadow only for the first four weeks)
- [ ] Schedule a 30-minute one-on-one with your team lead
- [ ] Schedule 15-minute intro chats with each team member
- [ ] Read the project README, the architecture docs, and the recent decision records

### Week 1: Learn by Reading
- [ ] Review the last ten merged pull requests to understand the review process and house style
- [ ] Read `coding.md` front to back, especially the enforcement hierarchy
- [ ] Read the repository's `AGENTS.md` and any package-level ones - this is the same context the agents work from
- [ ] Shadow a team member during an on-call shift or an incident
- [ ] Attend your first standup, planning session, and retro
- [ ] Explore the monitoring dashboards to understand what healthy looks like
- [ ] Deploy your first change to staging, even if it is a typo fix
- [ ] Submit your first pull request and get it reviewed and merged

### Weeks 2-4: Build Confidence
- [ ] Pick up a small bug fix or improvement from the backlog
- [ ] Pair with a senior engineer on a medium-complexity feature
- [ ] Write your first integration or end-to-end test
- [ ] Ship one change with heavy agent assistance and one entirely by hand, then compare where the review time went
- [ ] Give feedback on onboarding - what was confusing, what was missing?
- [ ] Update one documentation page with something you learned the hard way
- [ ] Review someone else's pull request, asking questions freely

### Month 2+: Full Contributor
- [ ] Own a feature from design through deployment
- [ ] Join the on-call rotation, initially with a backup
- [ ] Contribute to architecture discussions and decision records
- [ ] Add or improve one reusable skill, hook, or runbook in the repository
- [ ] Mentor the next new hire using the onboarding process you helped improve

## Onboarding an Agent

The repository itself needs to be onboardable. Run this checklist against your repo the same way you would run an accessibility audit - periodically, and honestly.

- [ ] **There is an `AGENTS.md` at the root** and it is current. Short and specific beats long and thorough; a file nobody maintains is worse than a small one that is true.
- [ ] **Nested context files exist where the rules differ.** Precedence is nearest-file-wins, so a package with its own conventions gets its own file rather than a paragraph buried in the root file.
- [ ] **Build and test commands are exact.** `npm run test:unit -- --run` is a command. "Run the unit tests" is a guess.
- [ ] **A single verification command exists** and is documented in the first ten lines of the context file.
- [ ] **Environment setup is reproducible without tribal knowledge.** Every required variable is in `.env.example` with a comment saying what it is for and where to get it.
- [ ] **MCP servers are documented and credentialed.** Which servers the repo expects, what each is for, what scope it needs, and which are read-only versus write-capable. A fresh clone should get the same wiring from the repo's MCP config.
- [ ] **Credentials for agent tooling are scoped and revocable.** Least privilege, short-lived, never a shared account, never production.
- [ ] **Generated and vendored directories are marked** so nobody - person or model - hand-edits a file the build will overwrite.
- [ ] **The things that must never happen are hooks, not sentences.** See the enforcement hierarchy in `coding.md`.
- [ ] **A new contributor can find where to start.** A handful of well-scoped "good first change" issues does as much for agent onboarding as it does for human onboarding.

## One-Command Verification

This is the single highest-leverage DX investment for agent-assisted work, and it is worth doing before almost anything else on this page.

Any contributor should be able to answer "is my change good?" with one command:

```bash
npm run verify
```

```json
{
  "scripts": {
    "verify": "npm run lint && npm run type-check && npm run test:unit -- --run",
    "verify:full": "npm run verify && npm run test:integration && npm run build",
    "start": "...",
    "test": "...",
    "lint": "...",
    "build": "...",
    "deploy": "..."
  }
}
```

Two rules make it work:

1. **It must be honest.** If `verify` passes and the change is broken, contributors stop trusting it and go back to running four commands in four terminals. Every time something reaches production that `verify` should have caught, add the check.
2. **It must be fast enough to run constantly.** If it takes four minutes, nobody runs it before pushing - and an agent iterating against a four-minute gate burns its budget waiting. Split it: a fast `verify` for the inner loop, a slower `verify:full` for pre-merge.

Keep the rest of the script names boringly consistent across every repository your team owns - `start`, `test`, `lint`, `build`, `deploy`, `verify`. Nobody should have to remember that one service uses `serve` and another uses `dev`. Consistency across repos is worth more than the perfect name in any one of them.

## Measuring the Loop

Slow feedback is the single biggest productivity killer, for people and for agents. Put real numbers in this document and treat a regression as a bug.

**Feedback-loop budgets** (replace with your own and enforce them in CI):

| Loop | Target | Alert above |
|------|--------|-------------|
| Hot reload after a save | under 1s | 3s |
| Type check (incremental) | under 5s | 15s |
| Unit test suite | under 15s | 45s |
| `npm run verify` | under 60s | 120s |
| Full CI pipeline | under 8 min | 15 min |
| Clean install and first boot | under 5 min | 10 min |

**Agent-loop metrics.** Build time is only half the picture once agents are writing diffs. These four tell you whether your context and your gates are actually working:

- **Time to verified** - from starting a task to a change that passes `verify`. This is the agent equivalent of build time, and it is dominated by how long your test suite takes. An agent iterating against a 90-second suite lives in a completely different economy from one iterating against a 12-second suite: the fast loop can afford to guess, check, and correct, while the slow loop has to be right the first time or burn the session.
- **First-pass acceptance rate** - what share of generated changes are merged without a human rewriting them. Low numbers usually mean the context file is missing conventions, not that the model is bad.
- **Human edit distance** - how much of a generated diff survives to merge. Track the pattern in what gets rewritten. If reviewers keep fixing the same class of thing, that class belongs in the context file or, better, in a lint rule.
- **Review findings per change** - and specifically the split between findings a scanner could have caught and findings that needed judgement. The first category should trend to zero; you fix it by writing a rule, not by reviewing harder.

Instrument these cheaply. A weekly manual sample of ten pull requests beats a dashboard nobody builds.

## Skills, Hooks, and Subagents

This is DX surface that did not exist a few years ago, and it goes stale silently. Keep an inventory in the repository and review it when you review the docs.

### Skills

A skill is a Markdown file with frontmatter that packages a repeatable procedure - a release checklist, a migration recipe, a report format. The platform loads only the name and description up front and pulls in the full body when the model judges it relevant, so a well-named skill costs almost nothing until it is used. That is the whole design argument against stuffing every procedure into your always-loaded context file.

Keep a table of what exists so people stop reinventing them:

| Skill | Use it for | Owner |
|-------|-----------|-------|
| `release-checklist` | Cutting and verifying a release | Platform |
| `add-api-endpoint` | Scaffolding a router, service, schema, and tests together | API |
| `migration-review` | Checking a migration for reversibility and lock risk | Data |
| `incident-writeup` | Producing a post-incident document in the house format | On-call |

### Hooks

Hooks are the deterministic half. They run on an event and cannot be reasoned out of running. Document which hooks exist and what each one blocks:

| Hook | Fires on | Blocks |
|------|----------|--------|
| `pre-commit` | Commit | Lint and format failures on staged files |
| `pre-push` | Push | Type errors, secret-shaped strings in the diff |
| `post-edit` | Any file edit by an agent | Writes to generated or vendored directories |
| `pre-merge` | CI | Missing tests on changed source files |

If a rule keeps getting violated despite being documented, that is not a discipline problem. It is a rule sitting in the wrong tier.

### Subagents

Say which work is parallelised and how the boundaries are drawn, because the failure mode is two agents editing the same file:

- Split parallel work by directory or module so no two runs touch the same file.
- Review agents are separate from authoring agents and are read-only. A reviewer that can edit the code it is reviewing can make its own finding disappear.
- Long research sweeps go to a read-only exploration agent that returns conclusions, not file dumps.

## Editor Setup and Productivity

Use whatever editor you like. What matters is that you have a binding for each capability below and that you can reach it without thinking. The names differ per editor; the capabilities do not.

| Capability | Why it matters | Common binding |
|------------|----------------|----------------|
| Fuzzy file open | Navigate by filename, never by folder tree | `Ctrl+P` |
| Go to symbol in file | Jump inside a long file | `Ctrl+Shift+O` |
| Go to symbol in project | Find a function without knowing its file | `Ctrl+T` |
| Go to definition / peek | Follow a call without losing your place | `F12` / `Alt+F12` |
| Search across files | The fallback that always works | `Ctrl+Shift+F` |
| Back / forward in history | Return from a definition dive | `Alt+Left` / `Alt+Right` |
| Multi-cursor on next match | Mechanical edits without a regex | `Ctrl+D` |
| Multi-cursor on all matches | Rename a local everywhere at once | `Ctrl+Shift+L` |
| Move / duplicate line | Restructure without cut and paste | `Alt+Up` / `Shift+Alt+Up` |
| Rename symbol project-wide | The safe rename - updates imports | `F2` |
| Quick fix / code action | Apply the linter's own suggestion | `Ctrl+.` |
| Toggle terminal and panels | Stay in one window | `Ctrl+` backtick |
| Restart the language server | Clears phantom type errors after a branch switch | Command palette |

The bindings shown are the common defaults in one popular editor. Fill in your own in a column next to them; a team where three people use three editors should have three columns, not three arguments.

Two editor-agnostic rules worth agreeing on:

- **Format on save, using the project's config.** Never a global config, never a personal override. Formatting diffs in a review are pure noise.
- **The project's linter and type checker run in the editor**, not only in CI. A rule you find out about eight minutes later in a pipeline is a rule you will resent.

### Shell Aliases and Shortcuts

Add these to your shell profile:

```bash
# Git shortcuts
alias gs='git status'
alias gd='git diff'
alias gds='git diff --staged'
alias gc='git commit -m'
alias gp='git push'
alias gpl='git pull --rebase'
alias gl='git log --oneline --graph -20'
alias gb='git branch --sort=-committerdate | head -10'
alias gco='git checkout'
alias gcb='git checkout -b'

# Project shortcuts
alias dev='pnpm dev'
alias verify='pnpm verify'
alias lint='pnpm lint'
alias build='pnpm build'
alias studio='pnpm db:studio'

# Docker shortcuts
alias dcu='docker compose up -d'
alias dcd='docker compose down'
alias dcl='docker compose logs -f'
alias dcp='docker compose ps'

# Quick navigation
alias proj='cd ~/projects/meridian'
alias projdocs='cd ~/projects/meridian/docs'
```

### The Fast Feedback Loop

Three panes: the dev server, a test watcher, and a scratch terminal for ad-hoc commands. The cycle:

```mermaid
flowchart TD
  A[Save a file] --> B[Dev server hot-reloads]
  A --> C[Test watcher reruns affected tests]
  B --> D{Behaviour correct?}
  C --> E{Tests green?}
  D -- no --> A
  E -- no --> A
  D -- yes --> F[Run npm run verify]
  E -- yes --> F
  F -- fails --> A
  F -- passes --> G[Commit and open a pull request]
```

The same loop is what an agent runs, just without the browser. That is why the numbers in the budget table above matter to both audiences.

## Debugging Workflows

### Frontend Debugging

**Component devtools** (browser extension):
- Component tree with props, state, and hooks
- Profiler for finding unnecessary re-renders
- Highlight-updates mode to see what redraws on a state change

**Network panel**:
```text
1. Open the browser devtools
2. Go to the Network tab
3. Filter to Fetch/XHR to see API calls
4. Click a request for headers, body, status, and timing
5. Right-click a request -> "Copy as cURL" to reproduce it in a terminal
   (also the fastest way to hand a failing request to an agent)
```

**Console debugging** when a breakpoint is overkill:
```typescript
console.table(users);                     // Tabular display of arrays and objects
console.group('Order Processing');        // Collapsible group
console.log('Subtotal:', subtotal);
console.log('Tax:', tax);
console.groupEnd();
console.dir(complexObject, { depth: 4 }); // Deep inspection
```

### Backend Debugging

**Breakpoint debugging** - preferred over log archaeology:
1. Set a breakpoint in the gutter next to the line number
2. Launch the configured debug target (`npm run dev:debug`, then attach your editor's debugger or a browser inspector client)
3. Trigger the code path
4. Step over, step into, continue
5. Inspect locals, and add expressions to the watch list

The launch configuration lives in the repository so every editor can use it. If yours only works on one machine, it is not a configuration, it is a personal habit.

**Database query debugging**:
```bash
# Enable ORM query logging in .env
DEBUG="orm:query"

# Or connect directly
psql postgresql://meridian@localhost:5432/meridian_dev

# Find the slow ones
SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;
```

### "It Works on My Machine" Checklist

When something works locally but fails for someone else, or in CI:

1. **Runtime version**: `node --version` - expect the version pinned in `.nvmrc`
2. **Branch state**: `git branch`, `git log -3`, `git status`
3. **Environment variables**: diff against `.env.example`, redact secrets
4. **Dependencies**: `pnpm list --depth=0` and compare
5. **Services**: `docker compose ps` - is everything healthy?
6. **Clean install**: `rm -rf node_modules && pnpm install`
7. **Fresh database**: `pnpm db:reset`
8. **Disk space**: `df -h` - container images fill disks quietly

## Common Gotchas

### 1. Hot Reload Not Working
**Symptom**: You save a file and the browser does not update.
**Fix**:
```bash
# If you see EADDRINUSE, another process holds the port
kill -9 $(lsof -t -i :3000)
pnpm dev
```

### 2. ORM Client Out of Sync
**Symptom**: The type checker flags model types you know exist.
**Fix**:
```bash
pnpm db:generate
```
Then restart your editor's language server. Generated client types are the most common source of type errors that are not really type errors.

### 3. Stale Container Data
**Symptom**: The database has old rows; tests fail on constraint violations.
**Fix**:
```bash
docker compose down -v    # -v removes volumes and all data
docker compose up -d
pnpm db:migrate
pnpm db:seed
```

### 4. Linter and Formatter Conflicts
**Symptom**: The two fight over formatting and the file changes on every save.
**Fix**: Make sure the formatter-compatibility config is the last entry in the linter's `extends` array, and that your editor is using the project's formatter config rather than a global one.

### 5. Import Path Errors After Moving Files
**Symptom**: `Cannot find module '@/components/OldPath'` after a rename.
**Fix**: Use your editor's rename-symbol command to move files - it rewrites imports. If the file has already been moved by hand:
```bash
grep -r "OldPath" src/
```
and update every reference in one commit.

### 6. Tests Flaky in CI
**Symptom**: Green locally, intermittently red in the pipeline.
**Common causes**:
- Timing-dependent assertions - wait for a condition, never for a fixed delay
- Tests that depend on execution order - each test sets up its own data
- Port conflicts between parallel test runs

A flaky test is worse than a missing one. It trains humans to re-run the pipeline and it trains agents that a red result is negotiable. Quarantine it, file it, fix it.

### 7. The Agent Is Confidently Wrong About the Codebase
**Symptom**: Generated code follows a pattern this repository abandoned two quarters ago.
**Cause**: The context file describes the old pattern, or does not mention it at all and the model fell back on what is common elsewhere.
**Fix**: Update `AGENTS.md`, and add an example of the current pattern. An explicit anti-pattern entry ("we no longer do X, we do Y") is more effective than describing Y alone.

### 8. Context Files Have Drifted
**Symptom**: Onboarding questions that the docs claim to answer.
**Fix**: Treat context files as code. They are reviewed in the pull request that invalidates them, and a "docs updated / not needed" line belongs in the PR template. If your build can verify a documented command still exists, make it.

### 9. An Agent Edited a Generated File
**Symptom**: A change works locally and vanishes on the next build.
**Fix**: Mark generated directories explicitly and add a hook that blocks writes to them. Do not rely on a sentence in the context file - see the enforcement hierarchy in `coding.md`.

### 10. A Missing Tool Server Looks Like a Wrong Answer
**Symptom**: An agent invents a table name or an issue number.
**Cause**: The MCP server that would have told it the truth is not configured, so it guessed.
**Fix**: Check the server list in the repository's MCP config against what is actually running. Make unavailability loud - an agent that reports "the schema server is unreachable" is far more useful than one that improvises.

## Runbook Library

Runbooks are the highest-return documentation your team writes, because they are the documents people read under stress. Keep them in the repository at `docs/runbooks/`, one file per task, and structure every one the same way: **when to use it, prerequisites, numbered steps with exact commands, how to verify success, how to roll back, who to escalate to.**

Start with these:

- Deploy to staging, and deploy to production
- Roll back a bad release
- Run and verify a database migration, and reverse one
- Rotate a credential or an API token
- Restore from a backup
- Respond to a page: triage, comms, and the writeup afterwards
- Add a new service to CI and to monitoring
- Onboard and offboard a team member, including credential revocation

A runbook with exact commands is also directly executable by an agent, which is the point. Vague steps ("update the config and redeploy") are the ones that fail at 2 am, whoever is reading them.

Alongside the runbooks, keep a **known friction points** page: every pain point you have not fixed yet, with its workaround and either a planned fix or an honest "not planned". Acknowledged friction is survivable. Undocumented friction makes every new contributor think they are the problem.

## Team Communication

### Daily Standup
- **When**: 10:00 local time, async in the standup channel for remote members
- **Format**: what I did, what I am doing, what is blocking me
- **Rule**: under two minutes. Deep dives move to a thread.

### Code Review Expectations
- **Response time**: within four business hours
- **Tone**: kind, specific, and explain the why
- **Prefixes**: `nit:`, `suggestion:`, `question:`, `concern:`, `blocker:`, `praise:`
- **Approval**: if only nits remain, approve with the nits noted
- **Provenance**: say when a change was largely agent-drafted. Not as an apology - it tells the reviewer where to look hardest.

### When to Escalate
- **Blocked for two or more hours**: post in the engineering channel with context
- **Production issue**: post in incidents, page on-call if it is user-facing
- **Architecture question**: open a discussion or book a 30-minute sync
- **Sensitive topic**: message your team lead directly

### Meeting Culture
- Default to async unless real-time is genuinely faster
- Every meeting has an agenda shared at least an hour ahead
- Notes posted in the relevant channel within an hour of the meeting ending
- Protect at least one no-meeting day a week

## Useful Scripts and Automations

### Pre-commit Hooks

The repository runs checks on commit. Husky is one common way to wire this up; native git hooks, lefthook, or your platform's own hook mechanism work equally well. Pick one and commit the configuration so everyone gets it from a clone.

```bash
# The pre-commit hook runs:
# 1. Linter on staged files
# 2. Formatter on staged files
# 3. Type check
# A failing check blocks the commit with an explanatory message.
```

Keep hooks fast. A pre-commit hook that takes 30 seconds gets bypassed, and a bypassed hook enforces nothing. Anything slow belongs in `pre-push` or CI.

### Database Snapshot and Restore
```bash
# Save the current state before testing a migration
pg_dump -h localhost -U meridian meridian_dev > db_snapshot.sql

# Restore
psql -h localhost -U meridian meridian_dev < db_snapshot.sql
```

### Quick Performance Check
```bash
time pnpm build          # Build time
time pnpm verify         # Inner-loop gate time
time pnpm test           # Test suite time
pnpm build && du -sh dist/*   # Output size
```

Run these on a schedule, not only when something feels slow. Feedback loops degrade a few hundred milliseconds at a time and nobody notices until the whole team has quietly changed how it works.

## Tracking Onboarding Friction

Survey every new developer at **one week, one month, and three months**. Three questions is enough:

1. What was confusing or missing?
2. What did you have to ask a person because the repository could not tell you?
3. What helped the most?

New-hire feedback is the most honest DX audit you will ever get, and it has a short shelf life - after three months they have internalised the workarounds and stopped seeing them. Question 2 is the one that matters most: every answer is a specific, fixable gap in the context files, the runbooks, or the setup script.

Run the same exercise against a fresh agent session on a cadence. Give it a small, well-defined task in a clean context and note every point where it had to guess. Its guesses land in the same places a new hire's questions do.

## Celebrating DX Improvements

Document before and after numbers for every DX improvement, and share them:

- Test suite: 90s to 12s
- Onboarding to first merged pull request: three days to four hours
- Clean install to running app: 18 minutes to five
- CI pipeline: 22 minutes to seven
- Time to verified on a typical agent-assisted change: 11 minutes to three

Quantified wins are what buys you the time to keep doing this work. "The build feels faster" gets you nothing at planning. "We cut 78 seconds off a loop that runs 200 times a day across the team" gets you the next sprint.

## Key Contacts

- **Team Lead**: [Name] - [handle] - architecture questions, priority decisions
- **Platform / DevOps**: [Name] - [handle] - CI/CD, infrastructure, deployments
- **Product Manager**: [Name] - [handle] - requirements, user stories, prioritization
- **Design Lead**: [Name] - [handle] - UX questions, specs, accessibility
- **On-Call**: check the incidents channel topic for the current rotation

## Learning Resources

### Internal
- **Architecture decision records**: `docs/adrs/`
- **Runbooks**: `docs/runbooks/`
- **Context files**: the root `AGENTS.md` and any package-level ones
- **Team wiki**: [link]
- **Recorded tech talks**: [link]
- **Pair programming**: ask anyone - we all do it

### External
- **Learning budget**: [amount] per year for conferences, courses, and books
- **Book and video subscription**: available through the company account
- **Conference speaking**: travel and registration covered if your talk is accepted