diff --git a/docs/codacy-ai/codacy-ai.md b/docs/codacy-ai/codacy-ai.md
index b169aea34f..4ace36f18e 100644
--- a/docs/codacy-ai/codacy-ai.md
+++ b/docs/codacy-ai/codacy-ai.md
@@ -78,7 +78,39 @@ More details about [AI Reviewer here →](../repositories-configure/integrations
 2. Navigate to the "Integrations" or "AI features" section (depending on your Codacy plan and UI version).
 3. Find "AI Reviewer", under "Status checks", and toggle the feature to "On" for the repository or organization scope you want to enable.
 4. Save your changes. Once enabled, Codacy will start adding a Summary to your pull requests based on the AI-enriched reviews.
-5. To request a PR Review from codacy, add a **`codacy-review`** label to your Pull Request. Codacy listens to the event and will publish the review as soon as it's ready.
+5. To request a PR Review from Codacy, add a **`codacy-review`** label to your Pull Request. Codacy listens to the event and will publish the review as soon as it's ready.
+
+#### Custom Instructions
+
+To improve the results of the AI Reviewer, you can provide custom instructions to the AI Reviewer. These instructions are specific to a repository and help the AI Reviewer understand the structure of the code, the business logic of the project, and your own preferences.
+
+These instructions are specified in a `review.md` file in the `.codacy/instructions` directory of your repository.
+
+You can kickstart this instructions file by asking your AI coding agent of choice to summarize the project and the codebase. Here is an example prompt:
+
+```markdown
+Analyze this repository and generate a concise AI PR reviewer instruction file in Markdown.
+
+The file should give a PR reviewer the essential context that won't be visible in a diff. Cover:
+
+- **Purpose**: What this repo does in 1-2 sentences.
+- **Architecture**: High-level structure, patterns used (e.g. MVC, event-driven, monorepo, etc.).
+- **Folder structure**: Key directories and what lives in each. Skip obvious ones.
+- **Stack**: Languages, frameworks, major libraries, and their roles.
+- **Testing**: Framework used, where tests live, what's expected to be tested.
+- **Code style & conventions**: Naming, file organization, formatting tools, any patterns enforced.
+- **PR-specific rules**: Branch strategy, what a PR should/shouldn't include, migration rules, etc.
+- **Common pitfalls**: Things reviewers should flag — anti-patterns, known gotchas, areas that break easily.
+- **Out of scope**: Anything reviewers should explicitly ignore or not enforce.
+
+Rules for the output:
+- Output only the Markdown content, no preamble or explanation.
+- Be concise. Every line should earn its place — no filler.
+- Use short sections with bullet points. Avoid long prose.
+- If something is not applicable or not inferable, omit the section entirely.
+```
+
+
 
 **Notes**
 
diff --git a/docs/repositories-configure/integrations/github-integration.md b/docs/repositories-configure/integrations/github-integration.md
index 9f673219d3..2526c8eaca 100644
--- a/docs/repositories-configure/integrations/github-integration.md
+++ b/docs/repositories-configure/integrations/github-integration.md
@@ -41,6 +41,9 @@ The AI Reviewer combines the reliability of deterministic, rule-based static cod
 
 It provides feedback on missing or weak tests, complex or duplicated code, and keeps security concerns up to date. Beyond that, it adds contextual insights about whether the changes follow the requirements, business rules, and logic used in the project.
 
+!!! tip
+    Improve the AI Reviewer results by providing custom instructions to the AI Reviewer. [Learn how to do it here →](../../codacy-ai/codacy-ai.md#custom-instructions).
+
 This setting can be enabled at a repository or organization level. Once enabled, Codacy will start adding a Summary to your pull requests based on the AI-enriched reviews. To request a PR Review from Codacy, add a **`codacy-review`** label to your Pull Request. Codacy listens to the event and will publish the review as soon as it's ready.