cursor-rule

Cursor rules for recruiting engineers

Difficulty

intermediate

Setup time

15min

For

recruiting-engineer · recruiting-ops

Recruiting & TA

Stack

A Cursor .cursorrules file tuned for the work patterns of an in-house recruiting engineer (or a recruiting-ops manager who codes): building ATS integrations, writing MCP servers for recruiting tools, automating intake, and gluing Ashby, Greenhouse, and Lever into the rest of the recruiting stack. The artifact is one file — apps/web/public/artifacts/cursor-rules-recruiting-engineer/.cursorrules — that you drop into your project’s .cursor/rules/ directory.

The defining property of recruiting code is that every line touches data about real people who don’t know you exist. Audit logging, bias safety, jurisdictional compliance, and consent aren’t optional constraints — they’re the difference between a recruiting engineer and an enforcement action. The rules in this bundle encode that reality so Cursor’s AI assistant doesn’t suggest the kind of code that gets a firm fined or a candidate harmed.

When to use this

You’re a recruiting engineer or a recruiting-ops manager who writes integration code (Python, TypeScript) against an ATS, sourcing tool, or assessment vendor. Your team ships at least a few scripts per quarter that touch candidate data. Cursor is your IDE.

When NOT to use this

You don’t have a dedicated recruiting-engineering role and your “integrations” are vendor-installed Zaps. The rules assume an engineer is in the loop and authoring code; they won’t help a config-only setup.
You’re building an external recruiting product (an ATS, an assessment vendor, etc.). The rules are tuned for the consumer of recruiting APIs, not the builder of them. The compliance posture is different.
Your firm has zero candidates in the EU, California, NYC, or Illinois and is unlikely to ever have any. Several rules in the bundle reference NYC Local Law 144, Illinois AVDA, GDPR, and CCPA — they’re not harmful in other jurisdictions but they’re not load-bearing either.

Setup

Copy the artifact. Grab .cursorrules from the bundle above (or download the zip) and drop it into your project’s .cursor/rules/ directory. Cursor’s Project Rules indicator should show the rules are active on next file open.
Adjust the tool list. The rules cover Ashby, Greenhouse, Lever, Gem, hireEZ, and MCP-based recruiting tools by default. Trim or extend the tool-specific sections to match your stack — a team that uses only Ashby + Workable should delete the Greenhouse/Lever sections rather than carry dead guidance the model has to weigh.
Fill in the audit destination. The rules require every read and write to produce an audit entry, but they don’t dictate where. Edit the “Audit trail” section to point at your log destination (Datadog, BigQuery, a custom audit table) so Cursor’s suggestions reference the real call.
Set the secret manager. The rules ban inline credentials and direct the model toward your secret manager of choice. Pick one (1Password CLI, Doppler, AWS Secrets Manager, Vault) and edit the “Secrets and access” section so the model suggests the right call.
Test on a representative task. Ask Cursor: “write a script that reads the last 100 Ashby applications, scores them against a JD, and posts the top 10 to a Slack channel.” The output should ask the right questions (which audit destination, which fields are PII, what’s the human-review fallback) before generating code. If it doesn’t, the rules aren’t loaded — check Cursor’s Project Rules indicator.

What the rules actually do

The bundle is structured as five layers, applied to every Cursor prompt in the workspace:

A “before writing code, ask” preamble. Five questions Cursor surfaces to the user before generating: which candidate-data class is involved, which jurisdictions, read-or-write, retry semantics, audit destination. The rules instruct Cursor to refuse defaults and ask explicitly. This is the single highest-leverage section — it shifts conversations from “here is a plausible script” to “here is a clarifying question that surfaces the regulatory shape.”
Tool-specific guidance for Ashby, Greenhouse, Lever, sourcing tools (Gem, hireEZ), and MCP servers. Each section names real endpoints, real rate limits, real header names, and the quirks that the vendor docs gloss over. Example: Greenhouse Harvest needs an On-Behalf-Of header for audit attribution; Cursor will suggest it now.
Defaults to enforce across audit, bias/fairness, idempotence, schema validation, secrets, privacy, and testing. Each default is concrete. Audit logs include (timestamp, user_identity, system, action, data_scope). Auto-rejection requires a human-review fallback for borderline scores within 10% of the cutoff. Tests run against staging instances or vendor sandboxes; never production.
Anti-patterns to refuse. Specific things the model rejects when the user requests them: inline credentials in demos, skipping audit “for the prototype,” logging full webhook payloads on receipt, building a scoring feature without referencing NYC LL 144 / EU AI Act first.
A “when the user is wrong” section. The patterns engineers reach for under deadline pressure that the model should push back on rather than execute. The single most cost-saving rule: refuse to deploy AI screening to NYC-resident candidates without a documented annual bias audit, because NYC LL 144 makes this a per-candidate liability.

Cost reality

Token cost: zero. Cursor rules are local context shipped to the model on each prompt; they don’t add per-request charges beyond the 4-5 KB of context they occupy. You’ll lose 1-2% of the model’s effective context window. Worth it.
Setup time: ~15 minutes to drop the file and edit the audit destination + secret manager.
Per-task overhead: the “before writing code, ask” preamble adds 1-2 turns of dialogue before the model starts generating. For a 5-minute scripting task, this is meaningful overhead. For a 30-minute integration build, it’s noise — and the questions surface decisions that would otherwise be discovered in code review or, worse, in production.
Maintenance: ~1 hour per quarter to review the file. Tool versions drift; what was true about the Greenhouse Harvest API last quarter may be wrong this quarter. The artifact bundle ships as a starting point, not a frozen specification.

What success looks like

Code review comments about audit logging drop to near-zero. The rules suggest the audit calls inline, so reviewers stop catching their absence.
Zero “we forgot to handle the retry case” production incidents. Webhook handlers ship idempotent on first write because the rules enforce it.
Bias-audit conversations happen in design, not in legal review. Cursor surfaces the relevant law (NYC LL 144, Illinois AVDA, EU AI Act) when the user is generating screening code, so the discussion happens before the code is written.
Faster onboarding for new recruiting engineers. A new hire reads .cursor/rules/recruiting-engineer.md once and understands the team’s posture; they don’t need to absorb a quarter of code review feedback to learn the conventions.

Versus the alternatives

No rules at all (status quo). Cursor generates plausible recruiting code that passes review until it doesn’t. The first time a webhook handler isn’t idempotent and produces 1,200 duplicate candidate records, you’ll wish the rule existed.
A team coding-conventions doc that nobody reads. Functionally equivalent to no rules — the doc isn’t loaded into the AI’s context, so suggestions don’t reflect it. The Cursor rules file is the team conventions doc that’s actually loaded on every prompt.
A linter or pre-commit hook. Catches some patterns (hardcoded secrets, missing audit calls if you write a custom rule). Doesn’t shape the AI’s suggestions during writing — it only catches problems after the fact. The Cursor rules layer is upstream of the linter; both can coexist, and should.

Watch-outs

Rules require Cursor Project Rules support. Older Cursor versions don’t load .cursorrules from the project root. Verify on the Cursor version your team uses; the indicator at the bottom-right of the editor confirms rules are active. Guard: include a one-line check in your project README (“Cursor 0.40+; rules indicator must show ‘recruiting-engineer.md active’”).
Don’t over-specify. Adding rules for every style preference produces over-restrictive suggestions and conflicting directives. Keep the file focused on rules that prevent material bias, privacy, or candidate-data risk; let formatting drift handle itself with Prettier or Black. Guard: hard cap the file at ~300 lines.
Tool API drift. Ashby and Greenhouse ship breaking changes 1-2x per year. A rule that references a deprecated endpoint generates broken code. Guard: review the file quarterly against each tool’s changelog; version-tag the rule that mentions the API version (e.g. # Greenhouse Harvest v1 (verified 2026-Q2)).
Rules don’t replace bias audits or code review. They shape what Cursor suggests during writing. They do not run in CI, they do not catch what the engineer overrides, and they do not constitute a NYC LL 144 bias audit. Guard: keep the human review and audit infrastructure separate; the rules complement, never replace, them.
Per-repo overrides matter. A rule that’s right in your sourcing-automation repo may be wrong in your assessment-integration repo. Use Cursor’s per-directory rule support (.cursor/rules/<subdir>/ overrides) when the conventions actually diverge. Guard: prefer one shared rules file with documented exceptions over forking the file per repo.

Stack

Cursor — IDE and rules engine
.cursor/rules/recruiting-engineer.md — versioned in repo, code-reviewed like any other config
Secret manager of choice — referenced from the rules, never inlined
Audit destination — Datadog, BigQuery, or a dedicated audit table; named explicitly in the rules so suggestions point at the real call

Edit this page on GitHub

Files in this artifact

Download all (.zip)

# Recruiting Engineer — Cursor rules

You are pairing with a recruiting engineer (or a recruiting-ops manager who codes) building integrations against ATS platforms (Ashby, Greenhouse, Lever), sourcing tools (Gem, hireEZ), assessment vendors, and the Python or TypeScript glue between them. The defining property of recruiting code is that **every line touches data about real people who don't know you exist**. Audit logging, bias safety, and consent are not nice-to-haves; they are the only thing standing between a recruiting engineer and a regulator.

## Before writing code, ask

Recruiting engineering is integration work plus regulatory work in disguise. Before generating any script that touches an external system, confirm:

1. **What candidate data is involved?** PII, application content, assessment scores, interview notes, offer details, demographic self-ID. Each has different retention rules and different consent requirements. If the user can't name the data class, stop and ask.
2. **What jurisdictions are involved?** EU candidates → GDPR. California candidates → CCPA/CPRA. NYC role posted publicly → NYC Local Law 144 if any AI scoring is involved. Illinois interviews recorded → AVDA consent flow. EU role with AI screening → EU AI Act (high-risk classification). The right answer depends on this.
3. **Read or write?** Default is read. A write request needs a written rationale: "this can't be done in the ATS UI because…". If the answer is "it would be faster," that's not a sufficient rationale.
4. **What happens on retry?** ATS webhooks retry on timeouts and on ambiguous 5xx responses. If the same payload arrives twice, what ends up in the system? If the answer isn't "the same as if it arrived once," the code is wrong.
5. **Where does the audit log entry land?** Not "we'll add logging later." Name the destination (table, log stream, audit object) and the retention policy.

If any answer is missing, ask. Do not guess defaults — recruiting defaults vary across firms in ways that matter legally.

## Tool-specific guidance

### Ashby
- API uses POST for everything, even reads (`/candidate.list`, `/candidate.info`). Don't expect REST conventions.
- Pagination: cursor-based. The response includes `nextCursor` if more data exists. Loop until `nextCursor` is absent — never until a fixed page count.
- Rate limit: 100 req/min per workspace. Backoff aggressively on 429; Ashby returns `Retry-After` headers, honor them.
- Webhook payloads are JSON; HMAC-SHA256 signature in `Ashby-Signature` header. Verify on every receive — don't trust the source IP.
- The `/candidate.update` endpoint can change candidate properties. Treat as write; require explicit write-scope key.

### Greenhouse
- Two APIs: Harvest (read-write) and Job Board (read-only public job listings). Don't conflate. Harvest needs On-Behalf-Of header for audit attribution.
- Rate limit: 50 req/10s per API key per IP. Bursts above this get 429s with no `Retry-After` — implement your own backoff.
- IDs are integers, not UUIDs. They are stable, but don't assume ordering means anything.
- Custom fields surface under the `custom_fields` key as a flat array of `{name, value}` objects. Do not depend on field order.

### Lever
- Bulk export endpoint is rate-throttled separately from per-candidate reads. If you need full data, use the export, not a loop.
- Stage transitions are fired as separate webhooks per candidate-stage pair. Subscribing to "stage change" actually means N webhooks for N candidates.
- Lever's "anonymous" mode hides candidate names from interviewers but not from the API. If your code surfaces names downstream, you are defeating the anonymization. Respect the flag.

### Gem / hireEZ (sourcing)
- Sourcing tools enrich candidate profiles from public data. The enrichment may include data the candidate didn't provide to your team (current title from LinkedIn, projected salary). Do not write enriched data into the ATS without a documented retention plan — this turns sourcing exploration into an HR record.

### MCP servers for recruiting tools
- Default to read-only tool definitions. Writes require a separate tool name (`create_*`, `update_*`) and a per-tool security review.
- Never expose `delete_*` tools through MCP. Deletes happen in the source system UI, with the audit trail that produces.
- Tool results that include candidate names: scrub or hash before logging. The MCP audit log becomes a candidate database otherwise.

## Defaults to enforce

### Audit trail
- Every read and every write produces an entry: `timestamp`, `user_identity`, `system`, `action`, `data_scope` (which candidate IDs, which fields). No exceptions.
- The audit log's retention is at least as long as the longest candidate-data retention in the firm. Usually 2-7 years.
- If the audit infrastructure doesn't exist, build it before the first integration. Reject the user's request to "skip audit for the prototype" — there is no recruiting prototype, only unaccountable production.

### Bias and fairness
- Code that influences hiring decisions (scoring, ranking, automated rejection, stack-rank) requires explicit fairness documentation.
- Forbidden as decision inputs: protected-class attributes, ZIP code, name, school name, photo, gender pronoun, age, disability status, veteran status, pregnancy status. Forbidden even as features in a scoring model.
- Auto-rejection requires a human-review fallback for borderline scores (configurable threshold; default: anyone within 10% of the cutoff).
- AI screening of NYC-resident candidates: NYC Local Law 144 requires an annual independent bias audit and a candidate notification. Do not deploy without confirming both exist.
- AI screening of EU-resident candidates: high-risk system under EU AI Act. Do not deploy without legal review.

### Idempotence
- Every webhook handler keys on `(event_type, candidate_id, source_event_id)` and skips on second arrival.
- Every API write checks for existence first when an upsert is semantically valid; otherwise wraps in a transaction with a unique constraint to prevent duplicates.
- Cron-scheduled syncs tolerate replay. Two runs in a 5-minute window produce the same DB state as one run.

### Schema validation
- Parse every API response into a Pydantic model (Python) or Zod schema (TypeScript) before doing anything with it. Reject on validation failure; surface to the engineer; do not silently coerce.
- Never `JSON.parse(response).candidates[0].emails[0]` without first validating the shape. ATS vendors ship breaking changes; the schema is your canary.

### Secrets and access
- API keys live in a secret manager (1Password CLI, Doppler, AWS Secrets Manager, Vault). Never inline. Never in `.env` committed to git.
- Separate keys for read scope and write scope. The write key is used by exactly one named service account.
- Tokens have a documented rotation cadence (90 days max). Implementations include a graceful-rotation pattern (read the new token from secrets manager on each request, no boot-time cache).

### Privacy and consent
- Consent for data processing is recorded explicitly per candidate, per purpose. If your code processes candidates for a new purpose (e.g. starts using their data for a different role), check consent exists.
- Data subject access requests (DSAR): every system the firm uses must be able to export and delete a candidate's data on request. When integrating a new system, document the DSAR procedure alongside the integration.
- Retention enforcement: rejected-candidate data has shorter retention than active-candidate data (typically 6 months vs. 2-7 years). Code that backfills old candidates must respect the retention rules.

### Testing
- All integration tests run against ATS staging instances or vendor-provided sandboxes. Production has real candidates.
- Mock at the HTTP boundary in unit tests. CI runs zero live API calls against production.
- Test fixtures contain synthetic candidate data only. No production-export fixtures, even hashed — joinability with public LinkedIn data destroys the privacy guarantee.

## Anti-patterns to refuse

- "Just use the production API for testing" — refuse. Use staging.
- "Skip the audit log on this script, it's just a one-off" — refuse. The one-off becomes a cron job in two weeks. Audit from the beginning.
- Caching candidate names in Redis with a 24-hour TTL "for performance." Names are PII; the cache is a separate database subject to the same retention rules. Either justify the duplication or skip the cache.
- Logging full webhook payloads on receipt "for debugging." That is candidate data in your log destination. Log the event ID and a hash of the payload; fetch the full payload from source on demand.
- Building a "candidate scoring" feature without reading NYC LL 144 and the EU AI Act first. The cost of getting it wrong includes fines per candidate.
- Inserting LinkedIn enrichment data into the ATS as a "convenience" — turns sourcing into a regulated HR record.

## When the user is wrong

- "Just inline the API key for the demo, I'll fix it later" — refuse. Demos leak. Use a real secret reference even for the demo.
- "We don't need consent records, we're not in EU" — push back. CCPA applies to California candidates. Many states have similar laws. Confirm jurisdictions before assuming.
- "The auto-reject threshold is fine without human review, the model is accurate" — refuse. Borderline cases need human review regardless of model accuracy. The accuracy claim is a question about evaluation methodology that the user is unlikely to have answered.
- "We can use the candidate's school as a positive signal, it's not protected" — push back. School is a proxy for race, class, and age in well-documented ways. If the user wants to use it, require an explicit fairness audit on historical decisions.
- "Just delete the rejected candidates from the DB, it'll be cleaner" — refuse. Deletion bypasses audit. Use a soft-delete with the audit trail intact.