Help me design and implement a code hook in an existing project. The hook platform or lifecycle is [HOOK PLATFORM AND EVENT]. The repository context, relevant files, runtime, and conventions are: [PROJECT CONTEXT]. The hook must do this: [REQUIRED BEHAVIOR] Its inputs, expected outputs or side effects, and failure behavior are: [INPUTS OUTPUTS AND FAILURE POLICY] Constraints include [CONSTRAINTS]. Existing related code or interfaces are: [RELATED CODE]. First inspect the supplied context and identify the exact lifecycle point, contract, and files that should change. Ask up to 3 clarifying questions only if a required interface, event contract, or failure policy is missing. Do not invent APIs, package versions, environment variables, files, or behavior that is not shown. Then produce: 1. A brief implementation plan naming the event timing, data flow, and why this hook is the correct extension point. 2. The complete code changes, organized by file path, with code ready to paste. Keep changes minimal and follow the existing style. 3. Tests covering the normal case, absent or malformed input, repeated invocation or idempotency where relevant, downstream failure, timeout or cancellation where relevant, and any security-sensitive boundary such as untrusted payloads, secrets, or permissions. 4. A short explanation of operational behavior: logging, error propagation, retry behavior, and how to disable or roll back the hook. 5. Commands I should run locally, using only commands justified by the supplied project setup. Before answering, verify that the hook cannot silently report success after a required side effect fails. Also check that asynchronous work is awaited or deliberately detached with a documented error path. Flag assumptions and compatibility risks instead of concealing them.
Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [HOOK PLATFORM AND EVENT] | Name the framework or tool and the exact event that triggers the hook. | Git pre-commit hook executed through Husky before a developer creates a commit. |
| [PROJECT CONTEXT] | Describe the language, framework, package setup, and relevant repository files. | TypeScript Node 20 monorepo using pnpm, lint-staged, Vitest, and a packages/api workspace. |
| [REQUIRED BEHAVIOR] | State what the hook must accomplish when it runs. | Block commits that add an unapproved public API endpoint without an adjacent OpenAPI entry. |
| [INPUTS OUTPUTS AND FAILURE POLICY] | Define data received, intended effects, return value, and what should happen on failure. | Read staged files from git; exit 1 with actionable paths if validation fails; exit 0 when no API routes changed. |
| [CONSTRAINTS] | List performance, security, compatibility, or deployment constraints. | Must finish under 10 seconds, work on macOS and Linux, and never inspect unstaged changes. |
| [RELATED CODE] | Paste relevant interfaces, existing hooks, or nearby implementation code. | Existing .husky/pre-commit runs pnpm lint-staged; route files live in packages/api/src/routes and specs in packages/api/openapi. |
How to use
- State the hook event precisely, such as pre-commit, webhook delivery, ORM lifecycle event, or CI callback.
- Paste the actual interface and one related implementation so the output follows your project rather than a generic pattern.
- Run the suggested tests and deliberately exercise the failure path before enabling the hook for a team.
- Follow up with: "Review this implementation as an adversarial maintainer and list the three most likely production failures with fixes."
Variations
Webhook handler
Use when receiving events from a third-party service.
Implement a production webhook handler for [PROVIDER] event [EVENT TYPE] in [LANGUAGE AND FRAMEWORK]. Here is the provider contract and existing route code: [CONTRACT AND CODE]. It must perform [REQUIRED ACTION] and handle duplicates according to [IDEMPOTENCY POLICY]. Produce the handler, signature verification, schema validation, idempotency storage approach, tests for invalid signatures and duplicated delivery, and error response rules. Do not invent provider headers or retry semantics; flag anything missing.
CI enforcement hook
Use when enforcing a repository rule in continuous integration.
Create a CI check for [REPOSITORY RULE] in [CI PLATFORM]. Repository layout and current workflows: [CONTEXT]. The check should inspect [TARGET FILES OR DATA] and fail with [FAILURE MESSAGE EXPECTATION]. Provide minimal workflow and script changes, unit tests where practical, fixture cases for valid and invalid inputs, and local reproduction commands. Account for shallow checkout, changed-file detection, forks, and path names with spaces. Do not assume secrets are available on pull requests.
ORM lifecycle hook
Use when adding validation or side effects around database writes.
Implement an ORM lifecycle hook for [MODEL] on [CREATE UPDATE DELETE EVENT] using [ORM AND VERSION]. Existing schema and service flow: [CODE CONTEXT]. Required behavior: [BEHAVIOR]. Define transaction boundaries, what happens on bulk operations, validation versus side effects, and failure handling. Produce paste-ready code and tests for one record, bulk writes, rollback, and concurrent updates. Do not put irreversible external calls inside a transaction without describing an outbox or compensation strategy.
Tips
- Choose the event by ownership of the invariant: enforce developer workflow rules at commit or CI time, but enforce data integrity at the application or database boundary.
- For inbound hooks, verify authenticity before parsing or acting on the payload, then make duplicate delivery safe with a durable event identifier.
- Keep hooks fast and narrow; a pre-commit hook that depends on a network service becomes a frequent bypass incentive.
- Make failure behavior explicit: blocking hooks should return actionable errors, while non-blocking side effects need durable logging, alerts, and a retry path.
FAQ
Should a hook fail open or fail closed?
Fail closed when the hook protects correctness, security, or a required record. Fail open only for genuinely optional work, and make the missed work visible and recoverable.
How should I test a hook?
Test the event contract and observable outcome, not just a helper function. Include duplicate calls, malformed data, exceptions from dependencies, and the behavior after partial failure.
Can AI infer my framework's hook API?
It can suggest likely patterns, but APIs vary by version. Paste the installed version and relevant documentation or interfaces so generated code does not rely on a guessed contract.