Before: A refactor quietly breaks an interface used by another language.
The contract travels with the file
The TypeScript renderer reads the exact shape declared by the Python compressor instead of guessing field names.
HINT for Software Engineers
Your coding agent writes fast. HINT keeps it inside your architecture.
HINT keeps plain-text engineering decisions beside the code they govern. Your agent reads only the relevant notes before it changes a file, so old constraints survive new sessions and new tools.
Where it helps
Three situations your team will recognize
Before: A familiar pattern is applied where the repository deliberately forbids it.
Local decisions beat generic habits
Architecture choices and rejected alternatives appear before implementation, while they can still change the approach.
Before: A happy-path patch ships without the errors and checks the system expects.
Failure behavior is part of the task
Error contracts, required flows and verification criteria arrive in the same scoped context as the code.
See it
A real renderer contract from the demo
The Pied Piper demo connects a Python compression stage to a TypeScript report renderer.
demo-pied-piper/renderer-ts/app.ts.hint ↗
# read ../compression-py/compressor.py
The incoming message is the `CompressionResult` emitted by the compression engine.
# func renderReport {#render_report}
## arg result
A validated `CompressionResult` mirroring the compressor output.What your assistant does next
It mirrors the upstream field names, follows the declared score formula, and reports any missing decision instead of inventing an interface.
What your AI assistant receives
<function_contract name="renderReport">
Read the upstream CompressionResult exactly.
Compute the score with the declared formula.
Return the specified report layout.
</function_contract>Your boundaries stay visible
What it will never do
- Invent an API, field or dependency that the repository does not declare.
- Replace a settled architectural decision with a generic preference.
- Report success when required error paths or tests are missing.
FAQ
Questions software engineers ask
Does this replace documentation?
No. It keeps the durable decisions an agent needs next to the paths they govern and links to longer sources when needed.
Does it work with an existing codebase?
Yes. Add small .hint files gradually; hint extract can draft structural starting points where a language adapter exists.
Is a model used to retrieve the rules?
No. Scoped lookup and local search are deterministic and run without a network call.
For your technical colleague
The vocabulary
A hintbook is a vocabulary for your profession—installed, not written by you.
decision- Records a settled engineering choice and why it was made.
invariant- States a property every change must preserve.
entity- Defines a domain object and its role.
field- Describes one field, including its type and constraints.
func- Specifies a function's inputs, output and behavior.
flow- Sets an ordered sequence that implementation must follow.
error- Names a failure condition and its required response.
test- Lists observable cases that prove the contract.
Manual setup
Bootstrap is read-only: it prints instructions for the assistant. The assistant performs the installation.
npm install -g @openhint/cli
hint config
hint add @openhint/hintbook-software-engineer
hint apply
hint verify renderer-ts/app.ts
hint emit renderer-ts/app.ts