Nark in an AI-native workflow

Last updated: July 23, 2026

TL;DR

AI writes fast, but it does not know your packages' runtime constraints. Nark encodes those constraints deterministically. Every pull request your AI generates gets a machine-checkable gate before merge, backed by author-cited rules from Stripe, Prisma, OpenAI, and the rest of the profile library.

The pattern

Cursor writes a helper that calls stripe.charges.create() with no try/catch. The code compiles. TypeScript is happy. The unit tests, which mock the Stripe client, all pass. ESLint is green. The human reviewer skims the diff, sees clean-looking code, and approves.

In production, a card declines. The unhandled error bubbles up somewhere unhelpful, the request returns a 500, the customer's checkout page shows a generic error, and your logging shows a stack trace with no context. The customer refreshes, thinks the charge went through, and files a support ticket four days later. Accounting catches the discrepancy months after that.

This is the AI-native failure mode. The code looks right. It passes every mechanical gate you have. Nothing in the toolchain knows that Stripe throws StripeCardError on declines and that swallowing it silently is wrong. Nark does. That behavior is written down in Stripe's own docs, and it is encoded in the Stripe Nark Profile.

Why AI review tools do not fix this

AI review tools (CodeRabbit, Cubic, cursor rules, Copilot review) are useful. They are also a different tool from Nark. The tradeoffs:

  • Non-deterministic. The same code reviewed twice can produce two different verdicts. A rule triggered on Monday may not trigger on Tuesday. Fine for style nudges. Weaker as a merge gate.
  • Pattern-inferred, not author-cited. Their rules are shaped by training data. When they flag a missing try/catch around a Stripe call, they are guessing from patterns. When Nark flags it, the rule links back to a specific line in Stripe's official docs.
  • Style over correctness. AI review is strong at "this variable name is confusing" and weaker at "this call can throw a specific error class that you are not handling". Nark inverts that ratio.

Use AI review for the style layer. Use Nark for the deterministic correctness backstop. They compose.

The Nark loop

  1. AI writes code.
  2. A pull request opens.
  3. Nark scans via the GitHub Action.
  4. Any new violation blocks the merge.
  5. The AI (or the human) reads Nark's specific violation plus fix hint and pushes a follow-up commit.
  6. Re-scan clears. PR merges.

The important word is "new". Existing violations are baselined and pass through. You do not have to fix your whole codebase to adopt Nark. You just have to stop shipping fresh regressions. In an AI-native codebase this matters more than it used to: the raw volume of PRs is up, the human attention budget per PR is down, and the surface area where a new violation can slip in expands with every accepted completion. The gate that used to be "did a senior engineer read this carefully" becomes "does this pass Nark". That gate is stable, cheap, and honest about what it does and does not check.

How this shapes team workflow

For the AI

Point your coding agent at the nark-fix skill. Claude Code, Cursor, and Windsurf can all load it. When Nark reports a violation, the agent reads the audit JSON, matches the postcondition to a known-good fix pattern, and proposes a diff. In practice this converts most Nark-flagged AI-generated blocks into a second automated commit that clears the check without human touch.

For the human reviewer

Nark's step-summary in the PR takes 30 seconds to scan. The reviewer sees "3 Nark violations, all in AI-generated blocks, all covered by known-good fix patterns" and focuses their attention on architecture and business logic. The error-handling nitpicks that used to eat up review time are handled by the machine gate.

Concrete integrations

  • Claude Code + Nark. Install the nark-fix skill. Run /nark-fix inside a Claude Code session and it walks the current scan output, proposing a fix per violation.
  • Cursor + Nark. Cursor reads the .nark/ suppressions file at the repo root. Once a violation is baselined or intentionally suppressed, Cursor stops relitigating it in every AI-generated block. Add the .nark/ directory to your Cursor rules so it treats suppression comments as ground truth.
  • Windsurf + Nark.Same pattern as Cursor. Windsurf's agent respects the .nark/ directory when it is referenced in the workspace rules.
  • GitHub Copilot + Nark. Copilot does not currently accept per-repo rule files the same way Cursor or Windsurf do. That is fine. Whatever Copilot ships, the Nark PR check catches on the way in. The loop closes at CI.

What Nark is not

  • Not an AI review tool. Nark's rules are hand-written, author-cited YAML profiles. The same code always produces the same result.
  • Not a lint plugin.Nark uses TypeScript's type checker to trace real package calls across imports, aliases, and property chains. It knows the difference between stripe.charges.create() and any random x.charges.create() because it resolves the type.
  • Not a security scanner. Nark catches runtime error-handling behavior. It is not a CVE scanner, a secrets scanner, or a SAST tool. Those live upstream and downstream of Nark in your pipeline.

Getting started

  • Wire the GitHub Action into one repo. Ten minutes end to end. See CI setup.
  • Install the nark-fix skill in whichever agent your team is using.
  • Ship one AI-generated PR through the loop. The first fix cycle is the demo. If it does not feel like a fair trade, tell us why: github.com/nark-sh/nark.

For our security posture, subprocessors, and compliance status see trust and SOC 2.