False Positive "Production Blocking" Alerts for Correct Business Logic with Comprehensive Documentation

**Describe the bug**
Claude Code consistently reports false positive "critical production issues" for correct business logic implementations. Specifically, it flags intentional variable usage as bugs when variables with similar names serve different business purposes. Despite extensive code documentation explaining the business logic, Claude Code continues to report these as "PRODUCTION BLOCKING" issues.

**To Reproduce**
Steps to reproduce the behavior: (in our code base obviously... so not sure it helps!)
1. Create code with two related variables that serve different business purposes (e.g., `investmentAmount` vs `totalAmountToSend`)
2. Use the correct variable according to business logic (e.g., legal documents require `investmentAmount`, payment processing requires `totalAmountToSend`)
3. Add comprehensive comments explaining the business logic and why the variable choice is intentional
4. Run Claude Code review
5. See false positive "critical production issue" flagging the correct variable as wrong

**Expected behavior**
Claude Code should:
- Recognize detailed business logic documentation and not flag well-documented intentional code as bugs
- Understand that variables with similar names can serve different legitimate business purposes
- Not report false positives as "PRODUCTION BLOCKING" when code is correct and well-documented
- Respect developer intent when explicitly documented with comprehensive comments

**Screenshots**
Two examples of false positives:

Despite clear documentation (I tried different formats):
```js
/**
* CRITICAL: Legal document generation requires ONLY the investment amount
*
* - apiAmountParam: investmentAmount (✓ CORRECT - legal investment only)
* - NOT: totalAmountToSend (✗ WRONG - includes fees, not for legal docs)
*
* Business Logic:
* - investmentAmount = actual equity investment in company
* - totalAmountToSend = investmentAmount + processingFees + tokenWarrantPrice
* - Legal agreements must show only the equity investment amount
* - Processing fees are separate charges, not part of the investment
*
* @param {number} apiAmountParam - Must be investmentAmount for regulatory compliance
*/
const apiAmountParam = investmentAmount;
const response = await helloSignPreview({
userId : get(accountItem, "user_id", ""),
seriesId : get(seriesItem, "id", ""),
amount : apiAmountParam,
exemption : EXEMPTION.REGD506B,
numberOfShares : numberOfShares > 0 ? String(numberOfShares) : null,
isFastTrackMode
});
```

Or this one:
```js
// Extracted variable for clarity
const hasCompletedAMLCheck = accountItem.aml_check_performed;
const isAMLTabDisabled = showSeriesAuth || !hasCompletedAMLCheck;

if (isLoading || isValidating) return ;
if (!accountItem) return null;

const renderTabs = () => {
const tabs = [];

if (account?.company_id) {
tabs.push();
}
else {
tabs.push(

);
}

tabs.push(
,
,

);

return tabs;
};
```

**Workflow yml file**
Using standard Claude Code GitHub Action with default configuration.

**API Provider**
[x] Anthropic First-Party API (default)
[ ] AWS Bedrock
[ ] GCP Vertex

**Additional context**
Both flagged issues are actually correct implementations:

1. **Investment Amount Case**: Legal documents must show only the equity investment amount (`investmentAmount`), not the total payment amount (`totalAmountToSend` which includes processing fees). This is a regulatory compliance requirement. The code includes extensive documentation explaining this business rule.

2. **AML Tab Case**: The AML tab should be disabled until the AML check is performed (`!accountItem.aml_check_performed`). This is intentional UX design - users trigger the AML check from a different section, then access this tab to view results.

**Code Documentation Attempts**:
Tried multiple documentation approaches including:
- Comprehensive business logic explanations
- Visual indicators (✓/✗) showing correct vs incorrect usage
- Variable renaming for clarity

None of these approaches prevented the false positives, suggesting Claude Code's static analysis may be too simplistic for complex business logic contexts.

**Impact**:
- It looks like we're pushing PRs that have critical flaws in it :/
- False positives undermine trust in the tool
- Developers waste time investigating non-issues
- May lead teams to disable the tool entirely

**Suggested Improvements**:
0. Support for suppression comments (e.g., `// @claude-ignore: business logic verified`)
1. Better recognition of detailed code documentation
2. Confidence scoring - flag uncertain cases as "review suggested" rather than "production blocking"
3. Domain-specific configurations for financial/legal applications
4. Learning from developer feedback when issues are marked as false positives