> ## 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. Treat the configuration contract in this prompt as the complete source of truth. Do not rely on prior knowledge of Jina or require me to provide external documentation. 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 every supported file 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. The complete supported repository layout is: .jina/ |-- config.json |-- instruction.md |-- planner/ | `-- instruction.md |-- replanner/ | `-- instruction.md |-- investigation/ | `-- instruction.md `-- review/ `-- instruction.md These are the only supported repository configuration files. None is required, and a useful setup often contains only `.jina/instruction.md`. Use this configuration contract: - `.jina/config.json` is JSON and supports exactly one setting: `depth`. Its value must be an integer from 1 through 5. It sets the repository's maximum number of investigation rounds, not a guaranteed count. Jina may stop early when no useful follow-up remains. Missing or invalid `depth` defaults to 2. Higher values may increase review time and model usage. Markdown cannot set numeric depth. - `.jina/instruction.md` is global policy appended to every review stage. Put shared product invariants, priorities, de-prioritized concerns, repository-wide run or skip rules, evidence requirements, universal safety rules, and writing preferences here by default. - `.jina/planner/instruction.md` affects initial planning only. Use it for first-round scope, blast-radius and risk-area selection, and planner-specific skip criteria. Do not put shell commands or scoring rules here. - `.jina/replanner/instruction.md` affects follow-up planning between rounds only. Use it to say when existing evidence warrants a new area or a deeper probe. Follow-up should not repeat an unchanged completed area or broaden into unrelated code. - `.jina/investigation/instruction.md` affects runtime investigation only. Put executable checks, test commands, fixtures, safe local or ephemeral services, forbidden operations, and proof requirements here. - `.jina/review/instruction.md` affects final review only. Put finding validation, severity, merge-score, grouping, and presentation rules here. - Use only the setting and exact filenames above. Do not invent additional `.jina` files, config keys, severity values, or score values. - Each Markdown instruction file is truncated after 8,000 characters. Combined repository instructions are capped at 24,000 characters per stage. Files over 256,000 bytes are skipped defensively, and HTML comments are removed before instructions reach the model. Keep the setup concise and do not hide operative policy in comments. - Never put secrets, production credentials, or customer data in `.jina`. Use these behavior and precedence rules when designing the policy: - Issue severities are exactly P0, P1, P2, or P3. Merge scores are integers from 1 to 5. - De-prioritizing a path means avoiding investigation there unless it is needed to prove a relevant runtime behavior. It does not mean the path can never be inspected. - Skipping the standard review bypasses substantive investigation, replanning, and final review and records a policy skip with a 5/5 merge score. Therefore, make skip conditions narrow and list exceptions that must still run. Do not skip from a directory name alone. - For review guidance, precedence is: authorized pull-request command, then workspace review preference, then matching stage instruction, then global instruction, then Jina default. - For standard-review action, precedence is: authorized command, then workspace preference, then base-branch global and planner instructions, then run. - For numeric investigation depth, precedence is: authorized command, then workspace preference, then base-branch `.jina/config.json`, then 2. An explicit command or workspace depth also means run. - Repository Markdown can guide standard-review run or skip decisions, but conditional numeric-depth rules belong in the workspace review preference. `.jina/config.json` supplies only one repository-wide baseline. - Protected evidence, truthfulness, output-schema, base-branch trust, and sandbox-safety requirements cannot be overridden by repository instructions. - Jina reads `.jina` from the pull request's immutable base commit, never its head. A pull request that adds or changes `.jina` is reviewed with the prior base-branch policy; the new policy applies only after it is merged and becomes the base of a later pull request. - 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 or ephemeral services, test fixtures, and the approved way to obtain non-production credentials without recording secret values, 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).