> ## Documentation Index > Fetch the complete documentation index at: https://docs.usejina.com/llms.txt > Use this file to discover all available pages before exploring further. # Configure .jina > Teach Jina what matters in your repository, how deeply to investigate, and what evidence your team expects. # 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. ```text Prompt for your coding agent theme={null} Help me configure Jina for this repository. Jina is an autonomous AI QA engineer that performs runtime investigations on pull requests. Do not edit files yet. First inspect the repository deeply enough to tailor the policy: - Read the README, contributor or agent instructions, architecture docs, package manifests, CI configuration, test setup, deployment configuration, and operational documentation. - Identify the runtime architecture, service boundaries, persistence and queue layers, external contracts, authentication model, critical product flows, and existing test commands. - Inspect git status and preserve all existing work. - If `.jina` exists, read each of the six supported files that is present and identify duplication or contradictions. - Do not ask me for facts you can learn from the repository. Summarize what you learned before asking questions. Use only this supported configuration contract: - `.jina/config.json` supports one key: integer `depth` from 1 through 5. It is the maximum number of investigation rounds; the default is 2 and Jina may stop early. - `.jina/instruction.md` contains global priorities, scope and skip rules, evidence requirements, safety rules, and writing preferences. Put policy here by default so it reaches every stage. - `.jina/planner/instruction.md` controls first-round scope, risk-area selection, and when repository policy may skip substantive standard investigation. - `.jina/replanner/instruction.md` controls evidence-driven follow-up and deepening between rounds. - `.jina/investigation/instruction.md` contains executable checks, fixtures, safe environment rules, forbidden operations, and proof standards. - `.jina/review/instruction.md` contains severity, merge-score, validation, and presentation policy. - Use only the config key and filenames listed above. - Keep issue severities exactly P0, P1, P2, or P3 and merge scores as integers from 1 to 5. - Protected evidence, truthfulness, output-schema, base-branch trust, and sandbox-safety requirements cannot be overridden. - Bias toward `.jina/instruction.md`. Do not split policy across stage files unless a rule is genuinely relevant to only one stage. After your repository summary, interview me in short, contextual batches. Ask only questions that materially affect the setup. Cover: 1. The product flows and invariants we cannot afford to break. 2. The highest-cost production failures for this system, including relevant authorization, tenant isolation, data integrity, idempotency, retry, compatibility, performance, deployment, or external-integration risks. 3. Which files, paths, generated artifacts, issue types, and low-value concerns to de-prioritize; when the entire standard review may be skipped; and which exceptions must always trigger a run. 4. The evidence required before Jina reports an issue: commands, tests, API calls, fixtures, logs, or reproductions. 5. Safe local services and credentials, plus commands, environments, endpoints, or data Jina must never use. 6. Our P0-P3 severity definitions, 1-5 merge-score rubric, false-positive tolerance, and preferred summary style. Preserve the fixed severity and score values. 7. The repository baseline depth from 1 to 5. Explain the likely review-time and model-usage tradeoff before asking me to choose. 8. Whether review action or depth should adapt by change type. For each change class, collect the standard action (`run` or `skip`), desired depth, and exceptions. Plan to return numeric adaptive-depth rules as a separate workspace review-preference snippet because `.jina/config.json` only sets the repository baseline. When the interview is complete: 1. Recommend the smallest useful `.jina` tree. Put reusable policy in the global instruction. Add `config.json` only when we want an explicit versioned baseline, and add a stage file only when it contains genuinely stage-specific policy. 2. Present the complete proposed tree and full contents of every proposed file. 3. Include a concise policy matrix: change class, standard action, depth, exceptions, and where the rule is configured. 4. Explain why each file exists, what it changes, and any policy you deliberately left out. 5. Check for vague exclusions, over-broad skips, duplicated rules, contradictory scoring, unsafe commands, secrets, invalid JSON, and instructions that attempt to override protected Jina behavior. 6. If adaptive numeric-depth rules are needed, include a separate workspace review-preference snippet and explain that an authorized workspace admin must save it in Jina settings. 7. Stop and wait for my explicit confirmation. Only after I confirm: - Create or update the approved `.jina` files and no unrelated source files. - Preserve useful existing guidance and existing uncommitted work. - Validate `config.json`, exact filenames, file sizes, internal consistency, and `git diff --check`. - Show the final diff summary and explain the effective baseline depth, stage policies, exclusions, evidence standard, scoring rubric, and workspace preference. - Remind me that Jina reads repository policy from the base commit, so this policy begins governing reviews only after it is merged and used as the base of a later pull request. ``` ## Quick start Create a global instruction with the risks and proof standards that matter to your team. ```markdown .jina/instruction.md theme={null} # Review policy ## Prioritize - Cross-tenant authorization failures. - Data loss, duplicate effects, and unsafe retries. - Backward-incompatible API or event changes. ## De-prioritize - Style, naming, and formatting without a behavior failure. - Generated files unless the change can alter production behavior. ## Evidence - Identify the triggering state, input, and affected path. - Prefer a repeatable command, test, API call, or probe. - Do not report speculative or pre-existing issues. ``` 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: ```text Repository tree theme={null} .jina/ ├── config.json ├── instruction.md ├── planner/ │ └── instruction.md ├── replanner/ │ └── instruction.md ├── investigation/ │ └── instruction.md └── review/ └── instruction.md ``` | File | What it controls | Add it when | | ------------------------------ | --------------------------------------- | --------------------------------------------------------- | | `config.json` | Maximum investigation rounds | You want an explicit repository depth | | `instruction.md` | Policy shared by every stage | Almost always; put policy here first | | `planner/instruction.md` | Initial risk areas and scope | Planning needs repository-specific direction | | `replanner/instruction.md` | Evidence-driven follow-up rounds | You want rules for going deeper | | `investigation/instruction.md` | Runtime checks, safety, and proof | Your stack needs specific commands, fixtures, or evidence | | `review/instruction.md` | Severity, merge score, and presentation | Your team uses a specific decision rubric | 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. ```json .jina/config.json theme={null} { "depth": 3 } ``` * 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. ```markdown .jina/instruction.md theme={null} ## Review action - Run when a change can affect runtime code, authorization, data, APIs, jobs, deployment, or infrastructure. - Skip substantive standard investigation only when the change cannot alter runtime behavior, deployment behavior, or an external contract. - Do not skip from a directory name alone. Check whether the changed file affects a direct dependency or generated runtime artifact. ``` ## Guide the planner The planner infers the pull request's intent, traces its blast radius, and chooses the first runtime areas to investigate. ```markdown .jina/planner/instruction.md theme={null} # Planning criteria - Trace changed handlers into authorization, persistence, queues, and external contracts. - Prioritize checkout, billing, and account-recovery flows when they are in the blast radius. - Include direct dependencies needed to prove a changed behavior. - Do not spend an area on docs, fixtures, or generated clients unless they can change runtime behavior. - Skip substantive investigation only when the change has no production execution path. ``` 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. ```markdown .jina/replanner/instruction.md theme={null} # Follow-up criteria - Add a round only when earlier evidence exposes a new dependency or plausible root cause. - Deepen an area when one focused probe can turn an inconclusive result into proof. - Carry forward the exact command, output, and state needed by the next investigator. - Do not broaden into unrelated code or repeat a path that was already validated. ``` 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. ```markdown .jina/investigation/instruction.md theme={null} # Investigation policy ## Preferred checks - Run the narrowest existing test before writing a new probe. - Use documented local fixtures for database and queue state. - Exercise changed API contracts with realistic request and identity data. ## Evidence standard - Capture the exact command and observed output. - Show the input or state that triggers the failure. - Confirm that the pull request caused the behavior. ## Safety - Use local or ephemeral services only. - Never call production, shared staging, or destructive maintenance endpoints. - Do not use real customer data or credentials. ``` 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. ```markdown .jina/review/instruction.md theme={null} # Review and scoring - Use 5/5 when no confirmed production-impact issue remains. - Use 4/5 for a confirmed concern that is safe to merge and follow up. - Use 3/5 when a well-evidenced issue should be fixed before a normal release. - Use 2/5 or 1/5 for validated failures that block important or core production behavior. - Keep the summary focused on the merge decision, root cause, and user impact. - Do not reduce the score for complexity or missing tests without a concrete failure. ``` 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. | What you want | Where to put it | | ---------------------------------------------------------------------- | ------------------------------ | | Risks that always matter | `instruction.md` | | Repository-wide file, path, or issue classes to de-prioritize | `instruction.md` | | Repository-wide conditions for running or skipping the standard review | `instruction.md` | | First-round area-selection rules | `planner/instruction.md` | | Hypotheses that do not deserve another round | `replanner/instruction.md` | | Conditions that do not meet your evidence bar | `investigation/instruction.md` | | Concerns that should or should not lower merge confidence | `review/instruction.md` | Start with explicit rules and exceptions: | Change class | Example standard-review policy | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Prose or docs only | Skip only when runtime behavior, deployment, and external contracts cannot change | | Generated output only | Skip only when its source and runtime consumers are unchanged | | Tests or fixtures only | De-prioritize, but run when the change exposes a production contract mismatch | | Auth, migrations, data, APIs, jobs, deployment, or infrastructure | Run; increase depth when the blast radius or failure cost is high | 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. | Decision | Highest to lowest priority | | ---------------------- | --------------------------------------------------------------------------------------------------------------------- | | Review guidance | Authorized `@usejina` command → workspace preference → matching stage instruction → global instruction → Jina default | | Standard review action | Authorized command → workspace preference → base-branch global and planner instructions → run | | Investigation depth | Authorized command → workspace preference → base-branch `config.json` → `2` | | Scenario review action | Authorized command → workspace preference → run, subject to the workspace automation gate | 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. ```text Workspace review preference theme={null} Review docs-only and low-risk UI changes lightly. Go deep on authentication, payments, tenant isolation, data migrations, and core infrastructure. Skip substantive standard investigation for generated-file-only changes only when their source and runtime consumers are unchanged. Run at the configured baseline when no rule matches. ``` An authorized pull request command can override the policy for one run: ```text Pull request comment theme={null} @usejina review depth 5 on the standard review and for scenarios go 2 layers deep ``` 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 | Rule | Behavior | | -------------------------------- | ------------------------------------------- | | Per Markdown file | Content after 8,000 characters is truncated | | Combined repository instructions | Capped at 24,000 characters per stage | | Defensive file read | Files over 256,000 bytes are skipped | | HTML comments | Removed before instructions reach the model | | Missing files | Normal; Jina uses defaults | Next, learn how Jina uses the [context graph](/concepts/context-layer) or see how it performs a [runtime investigation](/concepts/runtime-investigation).