HINT is a Markdown-native specification language. Declare what must be produced — in plain human intent, right next to the work — and HINT compiles it into a deterministic, high-density prompt your AI agent can't improvise around.
Compiles to prompts for Claude Code, Codex, Cursor & friends.
You ask for one thing and get plausible improvisation around it. HINT keeps both — your declarations become binding borders, the AI produces the work inside them, and gaps come back to you as reports instead of silent decisions.
A .hint file is pure Markdown. Nothing new to learn, instantly readable by humans and AI alike, with native highlighting in any editor.
Companion files sit next to their targets — login.ts.hint beside login.ts — and travel through the same reviews, branches, and history.
The same specs and the same hintbook always produce the same prompt. No hidden prompt engineering — compiled prompts are reviewable, diffable artifacts.
Every heading is a typed block — entity, clause, bad. Keyword, name, body. Heading depth nests the structure into a tree.
hintThe transpiler walks find → parse → compile, renders each block through your hintbook's templates, and wraps it in a role header and verification footer.
The high-density prompt tells the AI exactly what exists, what it must contain, what it must do, and what it must never do. Gaps come back, not guesses.
hint src/api/invoice.ts | claude -p
— one pipe, spec to working code.
hint apply writes the HINT workflow into your AGENTS.md and CLAUDE.md. After that, just keep working in normal dialogue — Claude Code, Codex, and Cursor read those instructions and call hint themselves whenever a .hint spec is relevant. You stay in the conversation; the borders come along automatically.
The transpiler understands only structure — files, headings, bodies. What each keyword means is supplied by hintbooks: installable packages of instruction templates. Swap the book, and the same files compile into a different profession's language.
Compiled output spells out exactly what exists, what it must contain, what it must do, and what it must never do — in explicit, binding tags.
A missing figure, party, or type is surfaced to you as a gap with its risk — never quietly filled with something plausible.
Publish your own hintbook as an npm package, a git repo, or a plain folder. Authoring one needs no code — if you can write Markdown, you can build it.
Sorted traversal, stable trees, pure interpolation — byte-identical prompts you can diff in CI. A hint.lock carries that determinism into the loop: unchanged specs are skipped, and fix reconciles only the blocks that drifted.
HINT isn't just a language for programmers — it's a professional intent layer over AI. It serves anyone whose work demands strict, structured thinking: the engineer knows the architecture, the lawyer knows the deal. HINT eliminates the mechanical production while keeping the decisions yours.
Architecture, data models, function contracts, anti-patterns
Contracts, clauses, obligations, red lines
Requirements, scenarios, edge cases
soonUser stories, acceptance criteria, scope
soonTest cases, negative paths, expected behavior
soonModels, assumptions, no invented numbers
soonPolicies, controls, red flags
soonScope, evidence, findings, severity
soonRFPs, scoring matrices, requirements
soonDoc structure, terminology, required sections
soonMetric definitions, formulas, constraints
soonAnswer policy, escalation, prohibited replies
soonRFP responses, value props, exclusions
soonProtocols, patient routing, checklists
soonModules, objectives, grading rubrics
soonRegulations, justifications, constraints
soonTone of voice, claims, brand safety
soonHINT pays off most wherever a wrong answer is expensive: analytics, compliance, finance, procurement, medicine, government, QA, documentation, and product. Anywhere the job means repeatable, high-stakes artifacts.
Thirty-plus keywords across intent, data, behavior, UI & constraints. Three modes: implement, fix, review.
Forty-plus keywords across the full anatomy of a legal norm. Three modes: draft, revise, audit.
Install the CLI, then mark the project root. hint config writes hint.yml; hint apply writes the HINT workflow into your AGENTS.md / CLAUDE.md.
Drop a .hint companion next to any file and compile — referenced specs are pulled into the same prompt automatically. Verify the result with hint verify, record it with hint lock; from then on, unchanged specs are skipped and fix reconciles only the blocks that drifted.
Keep the speed of AI and the control of a specification. Borders, not vibes.