# How to Provide Business Context Using Background Flags in Open-Code-Review

> Learn to provide business context in Open-Code-Review using background flags. Inject domain specific requirements into LLM prompts with --background or --background-file.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: how-to-guide
- Published: 2026-08-06

---

**You can provide business context to Open-Code-Review using the `--background` flag for inline strings or `--background-file` for Markdown files, which injects domain-specific requirements into LLM prompts via the `{{requirement_background}}` placeholder.**

Open-Code-Review (OCR) from Alibaba enables AI-assisted code reviews that understand your specific business requirements. When you need to communicate domain context—such as compliance rules, performance targets, or architectural constraints—you can provide business context using background flags to enrich the LLM's understanding. These flags integrate seamlessly into the CLI workflow and are processed through the `cmd/opencodereview` and `internal/agent` source files.

## Command-Line Background Options

OCR offers two complementary approaches to supplying business context, each handled through distinct flags registered in [`cmd/opencodereview/shared_flags.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/shared_flags.go).

### Inline Context with `--background`

The `--background` flag (short form `-b`) accepts a concise inline string that describes your requirement, goal, or domain-specific information. This option is ideal for quick, one-off reviews where the context fits in a single sentence.

When OCR executes, this value is stored in the `background` field of the command options struct (`reviewCmdOpts` in [`cmd/opencodereview/review_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/review_cmd.go) or `scanCmdOpts` in [`cmd/opencodereview/scan_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/scan_cmd.go)).

### File-Based Context with `--background-file`

The `--background-file` flag (short form `-B`) accepts a path to a Markdown file containing richer, structured business requirements. According to the source code in [`cmd/opencodereview/background_file.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/background_file.go), OCR resolves this path relative to the repository root using `resolveBackgroundFilePath`, then reads and sanitizes the content.

The system enforces a **soft limit of 2 KB** and a **hard limit of 8 KB** on the final background content to manage prompt sizes effectively.

## Combining Both Flags for Maximum Context

You can use both flags simultaneously to layer your business context. When both are provided, OCR merges the inline text with the file content using the `mergeBackground` function.

The inline `--background` value is placed before the file content, with appropriate delimiters inserted between them. This merged result then populates the `background` field used throughout the application.

```bash

# Combine inline hint with detailed requirements file

ocr review \
  --background "Focus on authentication flow security" \
  --background-file ./docs/compliance-requirements.md

```

## How Background Context Reaches the LLM

The path from CLI flag to LLM prompt involves several key components in the alibaba/open-code-review codebase.

### Flag Registration and Initial Processing

In [`cmd/opencodereview/shared_flags.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/shared_flags.go) (lines 27-29), the flags are registered:

```go
cmd.Flags().StringVarP(background, "background", "b", "", "optional requirement/business context for the review")
cmd.Flags().StringVarP(backgroundFile, "background-file", "B", "", "path to a Markdown file used as review background")

```

When a review command executes, if `opts.backgroundFile` is set, the system calls `resolveBackgroundFilePath(cc.RepoDir, opts.backgroundFile)` to locate the file, then `readBackgroundFile(bgPath)` to load its contents.

### Content Merging and Sanitization

The [`cmd/opencodereview/background_file.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/background_file.go) file (lines 16-23) implements the merging logic through `mergeBackground`. This function ensures proper delimiter separation between the inline text and file content while respecting the size limits.

### Prompt Injection Points

The final background string replaces the `{{requirement_background}}` placeholder in [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go) at two critical points:
- **Line 1149**: When constructing the *plan* prompt
- **Line 1473**: When constructing the *main task* prompt

The agent receives the background through `a.args.Background`, which it injects into the prompt template using `strings.ReplaceAll(content, "{{requirement_background}}", a.args.Background)`.

## Practical Usage Examples

Here are concrete ways to provide business context using background flags in your workflow:

```bash

# Simple inline background for a quick review

ocr review --background "Add rate-limiting to the login API"

# Use a comprehensive requirements document

ocr review --background-file ./docs/sprint-24-requirements.md

# Layer specific focus on top of general requirements

ocr review \
  --background "Prioritize SQL injection checks" \
  --background-file ./docs/security-standards.md \
  --target ./src/auth

```

## Technical Implementation Details

The background handling system includes specific safeguards to ensure reliability:

- **Path Resolution**: File paths are resolved relative to the repository root (`cc.RepoDir`), not the current working directory
- **Content Limits**: Soft limit of 2 KB and hard limit of 8 KB prevent token overflow in LLM prompts
- **Scope**: The [`internal/scan/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/scan/agent.go) file implements similar background handling for scan commands, ensuring consistency across both review and scan workflows
- **Sanitization**: Background file content undergoes sanitization before merging to remove potentially harmful characters or formatting

## Summary

- Use `--background` (`-b`) for short, inline business context strings that describe immediate requirements
- Use `--background-file` (`-B`) for detailed Markdown documentation with architectural or compliance context
- Combine both flags to layer specific focus areas on top of comprehensive documentation
- Background content is processed through [`cmd/opencodereview/background_file.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/background_file.go) and injected into prompts via the `{{requirement_background}}` placeholder in [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go)
- Size limits (2 KB soft, 8 KB hard) ensure optimal LLM performance without context overflow

## Frequently Asked Questions

### What is the maximum size for background context?

Open-Code-Review enforces a soft limit of 2 KB and a hard limit of 8 KB on background content. According to [`cmd/opencodereview/background_file.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/background_file.go) (lines 16-23), the `mergeBackground` function ensures the final string stays within these bounds to prevent prompt token overflow and maintain LLM processing efficiency.

### Can I use both `--background` and `--background-file` flags together?

Yes. When both flags are provided, OCR merges the inline text with the file content, placing the inline `--background` value before the file content with appropriate delimiters. This merged result is then injected into the LLM prompts via the `{{requirement_background}}` placeholder.

### Where does the background context appear in the review?

The background context appears in the LLM prompts constructed in [`internal/agent/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go). Specifically, the `{{requirement_background}}` placeholder is replaced with your business context at line 1149 (plan prompt construction) and line 1473 (main task prompt construction), allowing the AI to tailor its feedback to your specific domain requirements.

### Does background context work for scan commands?

Yes. Background flags function identically for both `ocr review` and `ocr scan` commands. The [`shared_flags.go`](https://github.com/alibaba/open-code-review/blob/main/shared_flags.go) file registers these flags for both operations, and [`internal/scan/agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/scan/agent.go) implements similar background handling to ensure consistent business context injection across all OCR workflows.