Agentic Engineering (a.k.a. "Vibe Coding")

Agentic engineering (a.k.a. "vibe coding") means using an LLM or agent – Cursor, Claude, Copilot, and others – to build features on Medplum. The biggest lever for quality is making your AI tools learn from Medplum's open-source code and docs rather than generic FHIR knowledge from the open internet.

Building AI into your application at runtime, such as clinical summarization, agents acting on patient data, or MCP-driven workflows, is a different topic; see Build with AI on Medplum. This page is about using AI to develop on Medplum.

Our Recommendations

1. Give your AI tools access to Medplum: clone the repo and link it in (preferred), give the agent docs and GitHub search, or connect the MCP server.
2. Plan and prompt with Medplum as the source of truth: have the model read the docs and code and propose patterns before it writes anything.
3. Keep conversations short and re-anchor on the docs: context decays over long sessions, so scope one task per thread and re-check work at checkpoints.
4. Verify and validate the output: check generated code against the type system and tests, review sensitive code by hand, and use Medplum's server-side validation where you can.
5. Encode your conventions in a rule file: a CLAUDE.md, Cursor rules, or AGENTS.md-style file keeps the agent pointed at Medplum's docs without being told each time, and the conventions survive compaction.

1. Give Your AI Tools Access to Medplum

Medplum is open-source with extensive docs on healthcare implementation patterns. When an LLM indexes on Medplum directly, results are significantly better; it pulls from valid snippets, real implementations, and trade-off guidance instead of guessing.

Option 1: Clone and Link the Repo (Preferred)

Agnostic to your LLM and editor:

1. Clone the repo: https://github.com/medplum/medplum
2. From your repo's top level, symlink your local copy:

    ln -s /absolute/path/to/medplum medplum-link
    ```

3. Prompt away, telling the model it can read `medplum-link/` (includes `packages/`, example apps, and `packages/docs`).

### Option 2: Search Docs and GitHub

If you'd rather not clone, give your agent search access; for example, one Claude Skill (or Cursor equivalent) that searches the [public docs](/content/docs/index.html) via Algolia, and one that searches the GitHub repo via the GitHub CLI (`gh`).

### Option 3: MCP Server

Medplum offers an MCP server for structured access to docs and data.

## 2. Plan and Prompt with Medplum as the Source of Truth

Lead with a planning prompt before implementation: have the model read the relevant docs and code, summarize the recommended pattern and trade-offs, and only then write code.

> Design patterns: I want a task-assignment service for a 50-state practice, where patients are seen by practitioners licensed in their resident state and clinical ops handles issues that don't need a licensed practitioner. Read the Medplum docs and explain the common design patterns I can use.

> Example implementations: I want video conferencing for virtual appointments plus patient photo and video uploads at intake. Find example implementations in the Medplum codebase I can reuse, and explain how they're deployed.

## 3. Keep Conversations Short and Re-Anchor on the Docs

Even when an agent starts with the right Medplum docs and code in context, quality degrades over a long session. Practical habits that keep the agent grounded:

- Scope one task per conversation. Finish a feature or fix, then start fresh rather than letting one thread sprawl across unrelated work.
- Re-pull the docs at checkpoints, not just at the start. Have the agent re-read the relevant docs and code after meaningful steps; for example, after it generates a FHIR resource, tell it to check that resource against the docs before moving on.
- Plan, then execute in a clean thread. Use a planning conversation to settle on the pattern, then open a new conversation to implement it with just the files that matter in context.
- Watch for drift. If the agent stops citing real Medplum snippets and starts producing plausible-but-generic FHIR, that's your signal to reset.

## 4. Verify and Validate the Output

An agent's confidence is not a measure of correctness. Build verification into your workflow so mistakes are caught by tooling and review, not in production.

### Easy Checks (No Data Access Needed)

- Type-check and compile: build the agent's code against the `@medplum/fhirtypes` types and run `tsc`. 
- Run the existing tests, lint, and build.
- Self-review against the docs.
- Mind the FHIR version.
- Review sensitive output by hand.

## 5. Encode Your Conventions in a Rule File

A rule or instructions file — `CLAUDE.md` for Claude Code, `.cursorrules` for Cursor, or an `AGENTS.md`-style file — is re-read on every turn. The most valuable part is the documentation block; pointing the agent at Medplum's docs as the source of truth is what makes it reach for them on its own.

```markdown
# Agent Rules for Medplum

## Documentation is the source of truth
- Medplum docs are at `medplum-link/packages/docs/docs/` — `[slug]` → that path + `.md`. Read with the file tools.

## Core

FHIR R4 only; type with `@medplum/fhirtypes`; reuse `@medplum/core` helpers; don't invent fields, search params, or operations.

## Common Mistakes

- Messaging: thread header carries no payload; `recipient` = ALL participants incl. the sender/creator.
- Scheduling: availability is implicit — create `Slot`s only for booked/blocked time, never for open availability.
- Idempotent writes: conditional create/update keyed on `identifier`, never search-then-create.
- Codes: agents routinely hallucinate SNOMED/LOINC/ICD-10 codes; don't invent them or pull them from the internet. When unsure, use a clearly-marked placeholder and flag it for human verification.

Before finishing: re-check your code against the list above; verify with `tsc` and tests.

Direct Data Access (Advanced)

Giving your AI tool direct access to your Medplum data, via an API access token or the MCP server, speeds things up but carries real caveats.