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

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.

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 or scanCmdOpts in 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, 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.

# 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 (lines 27-29), the flags are registered:

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 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 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:

# 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 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 and injected into prompts via the {{requirement_background}} placeholder in 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 (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. 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 file registers these flags for both operations, and internal/scan/agent.go implements similar background handling to ensure consistent business context injection across all OCR workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}