Skip to main content

Configure .jina

.jina is your repository-owned review policy. It tells Jina which risks matter, what noise to avoid, how to investigate safely, and how to score the result. Put policy in .jina/instruction.md first so it reaches every stage. Add a stage-specific file only when a rule belongs to that stage alone.

Generate .jina with your coding agent

Copy this prompt into a coding-agent CLI from the root of your repository. The agent will inspect the codebase, ask only the questions it cannot answer from the repository, and propose the smallest useful .jina setup before writing files.
Prompt for your coding agent

Quick start

Create a global instruction with the risks and proof standards that matter to your team.
.jina/instruction.md
Jina reads the policy after it reaches the base branch. The pull request that introduces it is reviewed with the previous base-branch policy.

Supported files

Jina reads these exact paths:
Repository tree
You do not need every file. Default to instruction.md; use a stage file only when the instruction would be irrelevant or misleading in other stages. Repeating policy across files makes reviews harder to tune.

Configure investigation depth

depth is the only supported config.json key.
.jina/config.json
  • Valid values are integers from 1 to 5.
  • The default is 2 when the file or a valid value is absent.
  • Depth is the maximum number of investigation rounds, not a guaranteed count.
  • Jina stops early when there is no useful follow-up work.
  • Each additional round can call the replanner and run more investigation agents, so a higher maximum may increase review time and model usage.
  • An invalid depth falls back to 2.
Choose the lowest maximum that gives Jina enough rounds to follow the dependency chains that matter in your repository.

Set global policy

.jina/instruction.md is appended to every review stage. Put durable repository-wide rules here:
  • Critical product flows and invariants.
  • Production risks worth prioritizing.
  • Noise, file classes, and issue classes to de-prioritize.
  • Repository-wide conditions for running or skipping the standard review.
  • Evidence and confidence requirements.
  • Universal safety or environment constraints.
  • Writing and concision preferences.
Keep stage-specific commands and scoring details in their matching files. Keep the numeric baseline depth in config.json; Markdown instructions do not replace it.
.jina/instruction.md

Guide the planner

The planner infers the pull request’s intent, traces its blast radius, and chooses the first runtime areas to investigate.
.jina/planner/instruction.md
Use this file for scope and selection. Do not put shell commands or merge-score rules here.

Guide the replanner

Between rounds, the replanner uses completed evidence to add new areas or deepen an inconclusive path. It cannot remove completed work or rerun the same area unchanged.
.jina/replanner/instruction.md
Use this file to favor depth over coverage for its own sake.

Guide runtime investigation

Investigation agents execute code in an isolated checkout. Tell them how to exercise your stack and what counts as proof.
.jina/investigation/instruction.md
Good instructions name real commands, fixtures, local services, and forbidden operations. Never put secrets in .jina.

Define review and scoring

The final reviewer validates findings, removes proven false positives, groups related failures, assigns severity, and produces the merge score.
.jina/review/instruction.md
You can revise the meaning and human-readable labels of the rubric, but the public contracts stay fixed:
  • Issue severity is exactly P0, P1, P2, or P3.
  • Merge score is an integer from 1 to 5.
  • Evidence-backed issues cannot be hidden by a reporting preference.
Define what is reportable in the global and investigation policies. Use the review file to control validation, scoring, and presentation.

Decide when to de-prioritize files or skip a review

These are different controls:
  • De-prioritize a file or path: Jina avoids spending an investigation area there unless it is needed to prove a relevant runtime path.
  • Skip the standard review: Jina bypasses substantive investigation, replanning, and final review. It records a policy skip with a 5/5 merge score.
Put reusable scope and run-or-skip policy in .jina/instruction.md whenever possible. Use a stage file only for a stage-specific decision. Start with explicit rules and exceptions: This table is a starting point, not a built-in Jina default. Adapt it to your repository. Avoid rules such as “ignore tests” or “skip docs”; they hide meaningful exceptions.

Understand precedence

Jina keeps repository defaults stable while allowing an authorized team member to adapt a specific review. An explicit manual or workspace depth also means “run” at that source. An explicit action without a depth allows the next source to supply the depth. Jina’s fixed evidence, truthfulness, output-format, trust-boundary, and sandbox-safety rules always remain in force.

Configure adaptive reviews

Use three layers:
  • Repository baseline: Set depth from 1 to 5 in .jina/config.json.
  • Adaptive team policy: Use the workspace review preference to vary standard and Scenario action or depth by change type.
  • One review: Use an authorized @usejina command for a pull-request-specific override.
Repository Markdown can guide whether the standard review runs or skips. Repository numeric depth comes only from config.json; put conditional numeric-depth rules in the workspace preference.
Workspace review preference
An authorized pull request command can override the policy for one run:
Pull request comment
Standard and Scenario depth resolve independently. The repository’s Scenario automation setting remains a separate gate and cannot be bypassed by review text.

Trust and rollout

  • Jina loads .jina from the pull request’s immutable base commit, never its head.
  • A pull request cannot weaken the policy used to review itself.
  • Review .jina changes like code, merge them, then evaluate them on a later pull request.
  • Change one dimension at a time and compare issue quality, review time, and model usage.
  • Run-specific commands and workspace preferences can override repository guidance, but only from authorized sources.

Limits

Next, learn how Jina uses the context graph or see how it performs a runtime investigation.