docs: comprehensive v2.2.0 documentation update#442
Merged
justn-hyeok merged 1 commit intomainfrom Apr 1, 2026
Merged
Conversation
Update all docs for v2.2.0: pre-analysis layer, hallucination filter, specialist personas, suggestion verification, triage digest, reviewContext config, and updated architecture diagrams. README.ko.md fully rewritten from v2.0.0-rc.1 to v2.2.0. Closes #336. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
📝 WalkthroughWalkthroughDocumentation restructure updating the review pipeline architecture from 4 layers to 6 stages, introducing Pre-Analysis and Hallucination Filter stages, documenting specialist personas configuration, and archiving outdated v3 design references with current architecture pointers. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/AGENTS.md (1)
23-35:⚠️ Potential issue | 🟡 MinorFix stale architecture pointer in AI-agent instructions.
This file now labels
3_V3_DESIGN.mdas historical, but Line 34 still tells readers to use it for the current architecture. Update that step toARCHITECTURE.mdto avoid misrouting.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/AGENTS.md` around lines 23 - 35, Update the "Working In This Directory" step that currently references `3_V3_DESIGN.md` as the current architecture to point to `ARCHITECTURE.md` instead: locate the bullet list under "For AI Agents" / "When exploring CodeAgora" and replace the mention of `3_V3_DESIGN.md` (the second item) with `ARCHITECTURE.md` so the instructions correctly direct readers to the current architecture doc.
🧹 Nitpick comments (3)
docs/ARCHITECTURE.md (1)
3-3: Add parent-document header comment.Please add a
<!-- Parent: ... -->header at the top for docs consistency.As per coding guidelines, "Include a
<!-- Parent: ... -->header comment linking to parent documents".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ARCHITECTURE.md` at line 3, Add a parent-document header comment at the very top of ARCHITECTURE.md by inserting a single HTML comment like <!-- Parent: <ParentDocName> --> above the existing content (above the "## 6-Stage Pipeline" heading); replace <ParentDocName> with the canonical parent doc title or link used elsewhere in the docs to maintain consistency.docs/CONFIGURATION.md (1)
1-1: Add parent-document header comment.Please add
<!-- Parent: ... -->at the top of this doc.As per coding guidelines, "Include a
<!-- Parent: ... -->header comment linking to parent documents".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/CONFIGURATION.md` at line 1, Add a parent-document header comment at the very top of the file by inserting a single HTML comment like <!-- Parent: <parent-document-name-or-path> --> immediately before the "# Configuration" heading; replace <parent-document-name-or-path> with the canonical parent doc identifier used across the repo so the file begins with that Parent header comment.docs/3_V3_DESIGN.md (1)
1-2: Add parent-document header for guideline compliance.Please add a top-of-file parent header comment (e.g.,
<!-- Parent: ... -->) to match docs conventions.As per coding guidelines, "Include a
<!-- Parent: ... -->header comment linking to parent documents".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/3_V3_DESIGN.md` around lines 1 - 2, Add a top-of-file parent header comment to comply with docs conventions by inserting a single HTML comment like <!-- Parent: ARCHITECTURE.md --> at the very top of the document (above the existing "**Note**: This document describes the original v3 design..." line) so the file includes the required parent-document linkage.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/ARCHITECTURE.md`:
- Line 40: Update the "Confidence scoring" line so it matches the actual verdict
logic: change the documented threshold that routes CRITICAL+ issues to
NEEDS_HUMAN from "0%" to "≤15%" (or "15% and below") and ensure the surrounding
text that mentions confidence-routing (occurrences at other locations like the
duplicate at the other referenced line) is updated to reflect the same ≤15%
threshold so operator guidance matches the implementation.
In `@docs/CONFIGURATION.md`:
- Around line 83-105: The example and types for reviewContext are inconsistent
with the actual schema: update the JSON example and the type table so
reviewContext uses the correct shapes—set deploymentType to one of the schema
enum values, change notes from a string to notes: [string], change
bundledOutputs from a boolean to bundledOutputs: [string], and replace pathRules
object map with pathRules: [{ pattern: string, notes: string[] }] (keep
verifySuggestions as boolean if that matches the schema); update both the JSON
snippet and the corresponding table rows for `deploymentType`, `notes`,
`bundledOutputs`, and `pathRules` to reflect these exact types and example
values (referencing reviewContext, deploymentType, notes, bundledOutputs,
pathRules, verifySuggestions).
In `@README.ko.md`:
- Around line 469-489: Update the reviewContext example so it matches the actual
schema: change deploymentType to one of the allowed enum values, make notes a
string[] (array), replace bundledOutputs boolean with an array of string pattern
entries, and convert pathRules from a map into an array of objects each with
pattern and notes[] fields; ensure verifySuggestions remains typed as in the
schema and mirror the exact shapes shown in CONFIGURATION.md for reviewContext
to keep examples consistent.
---
Outside diff comments:
In `@docs/AGENTS.md`:
- Around line 23-35: Update the "Working In This Directory" step that currently
references `3_V3_DESIGN.md` as the current architecture to point to
`ARCHITECTURE.md` instead: locate the bullet list under "For AI Agents" / "When
exploring CodeAgora" and replace the mention of `3_V3_DESIGN.md` (the second
item) with `ARCHITECTURE.md` so the instructions correctly direct readers to the
current architecture doc.
---
Nitpick comments:
In `@docs/3_V3_DESIGN.md`:
- Around line 1-2: Add a top-of-file parent header comment to comply with docs
conventions by inserting a single HTML comment like <!-- Parent: ARCHITECTURE.md
--> at the very top of the document (above the existing "**Note**: This document
describes the original v3 design..." line) so the file includes the required
parent-document linkage.
In `@docs/ARCHITECTURE.md`:
- Line 3: Add a parent-document header comment at the very top of
ARCHITECTURE.md by inserting a single HTML comment like <!-- Parent:
<ParentDocName> --> above the existing content (above the "## 6-Stage Pipeline"
heading); replace <ParentDocName> with the canonical parent doc title or link
used elsewhere in the docs to maintain consistency.
In `@docs/CONFIGURATION.md`:
- Line 1: Add a parent-document header comment at the very top of the file by
inserting a single HTML comment like <!-- Parent: <parent-document-name-or-path>
--> immediately before the "# Configuration" heading; replace
<parent-document-name-or-path> with the canonical parent doc identifier used
across the repo so the file begins with that Parent header comment.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 7d382681-362e-437f-89be-40d013c8a90c
📒 Files selected for processing (7)
CLAUDE.mdREADME.ko.mdREADME.mddocs/3_V3_DESIGN.mddocs/AGENTS.mddocs/ARCHITECTURE.mddocs/CONFIGURATION.md
| │ ① File/line validation against actual diff │ | ||
| │ ② Self-contradiction detection │ | ||
| │ ③ Evidence deduplication (merge duplicates) │ | ||
| │ ④ Confidence scoring (0% → NEEDS_HUMAN) │ |
There was a problem hiding this comment.
Confidence-routing threshold is documented incorrectly.
The doc says only 0% confidence routes CRITICAL+ issues to NEEDS_HUMAN, but verdict logic indicates a broader low-confidence threshold (≤15%). Please align these lines to actual behavior to avoid incorrect operator expectations.
Proposed doc fix
-│ ④ Confidence scoring (0% → NEEDS_HUMAN) │
+│ ④ Confidence scoring (low confidence, e.g. ≤15% for CRITICAL+ → NEEDS_HUMAN) │
...
-4. **Confidence-based verdict**: Issues with 0% confidence at CRITICAL+ severity route to NEEDS_HUMAN instead of REJECT
+4. **Confidence-based verdict**: Low-confidence CRITICAL+ issues (e.g., ≤15%) route to NEEDS_HUMAN instead of REJECTAlso applies to: 75-75
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/ARCHITECTURE.md` at line 40, Update the "Confidence scoring" line so it
matches the actual verdict logic: change the documented threshold that routes
CRITICAL+ issues to NEEDS_HUMAN from "0%" to "≤15%" (or "15% and below") and
ensure the surrounding text that mentions confidence-routing (occurrences at
other locations like the duplicate at the other referenced line) is updated to
reflect the same ≤15% threshold so operator guidance matches the implementation.
Comment on lines
+83
to
+105
| ```json | ||
| { | ||
| "reviewContext": { | ||
| "deploymentType": "production", | ||
| "notes": "Auth module refactoring in progress", | ||
| "bundledOutputs": true, | ||
| "pathRules": { | ||
| "src/auth/**": "builtin:security", | ||
| "src/api/**": "builtin:api-contract" | ||
| }, | ||
| "verifySuggestions": true | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | `deploymentType` | `string` | Deployment context: `"production"`, `"staging"`, `"internal"` | | ||
| | `notes` | `string` | Free-text notes passed to reviewers as project context | | ||
| | `bundledOutputs` | `boolean` | Whether to include bundled outputs in review | | ||
| | `pathRules` | `object` | Glob-to-persona mapping for path-specific specialist review | | ||
| | `verifySuggestions` | `boolean` | Enable tsc transpile check on CRITICAL+ suggestions | | ||
|
|
There was a problem hiding this comment.
reviewContext example/types do not match the actual config schema.
This section currently documents invalid shapes:
deploymentType: "production"(not in enum)notesasstring(schema isstring[])bundledOutputsasboolean(schema isstring[])pathRulesas object map (schema is array of{ pattern, notes[] })
Please align the JSON example and the type table with the schema to prevent invalid configs.
Proposed doc fix
{
"reviewContext": {
- "deploymentType": "production",
- "notes": "Auth module refactoring in progress",
- "bundledOutputs": true,
- "pathRules": {
- "src/auth/**": "builtin:security",
- "src/api/**": "builtin:api-contract"
- },
+ "deploymentType": "web-app",
+ "notes": ["Auth module refactoring in progress"],
+ "bundledOutputs": ["dist/**/*.js"],
+ "pathRules": [
+ { "pattern": "src/auth/**", "notes": ["Prioritize security review"] },
+ { "pattern": "src/api/**", "notes": ["Check API contract compatibility"] }
+ ],
"verifySuggestions": true
}
}
@@
-| `deploymentType` | `string` | Deployment context: `"production"`, `"staging"`, `"internal"` |
-| `notes` | `string` | Free-text notes passed to reviewers as project context |
-| `bundledOutputs` | `boolean` | Whether to include bundled outputs in review |
-| `pathRules` | `object` | Glob-to-persona mapping for path-specific specialist review |
+| `deploymentType` | `string` | One of: `github-action`, `cli`, `library`, `web-app`, `api-server`, `lambda`, `docker`, `edge-function`, `monorepo` |
+| `notes` | `string[]` | Free-form context lines passed to reviewers |
+| `bundledOutputs` | `string[]` | Glob patterns treated as bundled outputs |
+| `pathRules` | `{ pattern: string, notes: string[] }[]` | Path-based review notes by glob |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/CONFIGURATION.md` around lines 83 - 105, The example and types for
reviewContext are inconsistent with the actual schema: update the JSON example
and the type table so reviewContext uses the correct shapes—set deploymentType
to one of the schema enum values, change notes from a string to notes: [string],
change bundledOutputs from a boolean to bundledOutputs: [string], and replace
pathRules object map with pathRules: [{ pattern: string, notes: string[] }]
(keep verifySuggestions as boolean if that matches the schema); update both the
JSON snippet and the corresponding table rows for `deploymentType`, `notes`,
`bundledOutputs`, and `pathRules` to reflect these exact types and example
values (referencing reviewContext, deploymentType, notes, bundledOutputs,
pathRules, verifySuggestions).
Comment on lines
+469
to
+489
| "reviewContext": { | ||
| "deploymentType": "production", | ||
| "notes": "인증 모듈 리팩토링 중", | ||
| "bundledOutputs": true, | ||
| "pathRules": { | ||
| "src/auth/**": "builtin:security", | ||
| "src/api/**": "builtin:api-contract" | ||
| }, | ||
| "verifySuggestions": true | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| | 필드 | 설명 | | ||
| |------|------| | ||
| | `deploymentType` | 배포 유형 (production, staging, internal) | | ||
| | `notes` | 리뷰어에게 전달할 프로젝트 컨텍스트 메모 | | ||
| | `bundledOutputs` | 번들된 출력 포함 여부 | | ||
| | `pathRules` | 경로별 전문 페르소나 매핑 | | ||
| | `verifySuggestions` | CRITICAL+ 제안에 tsc 트랜스파일 검증 활성화 | | ||
|
|
There was a problem hiding this comment.
reviewContext 예시가 실제 스키마와 맞지 않습니다.
현재 예시는 실제 설정 스키마와 타입/형태가 다릅니다:
deploymentType: "production"(허용 enum 아님)notes는string[]이어야 함bundledOutputs는boolean이 아니라string[]패턴 목록pathRules는 맵이 아니라{ pattern, notes[] }[]배열
한국어 문서도 docs/CONFIGURATION.md와 동일한 스키마 형태로 맞춰 주세요.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.ko.md` around lines 469 - 489, Update the reviewContext example so it
matches the actual schema: change deploymentType to one of the allowed enum
values, make notes a string[] (array), replace bundledOutputs boolean with an
array of string pattern entries, and convert pathRules from a map into an array
of objects each with pattern and notes[] fields; ensure verifySuggestions
remains typed as in the schema and mirror the exact shapes shown in
CONFIGURATION.md for reviewContext to keep examples consistent.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
README.ko.mdfrom v2.0.0-rc.1 to v2.2.0 (badges, test counts, architecture diagram, GitHub Actions ref, new sections)docs/3_V3_DESIGN.mdpointing to currentARCHITECTURE.md(closes docs: V3 design doc describes unimplemented Claude Code skill architecture #336)Files changed
CLAUDE.md— 6-stage pipeline, security updates (0o700 dir perms, fail-closed)README.md— new "How It Works" diagram with Pre-Analysis + Filter stagesREADME.ko.md— major overhaul: 2846 tests, v2.2.0 badge, new architecture diagram, reviewContext/persona/AI rules/artifact exclusion sections,bssm-oss/CodeAgora@v2action refdocs/ARCHITECTURE.md— full pipeline diagram with Pre-Analysis and Hallucination Filter layersdocs/CONFIGURATION.md— reviewContext, specialist personas, .reviewrules, external AI rules, artifact exclusiondocs/AGENTS.md— updated architecture referencesdocs/3_V3_DESIGN.md— added note redirecting to ARCHITECTURE.mdTest plan
grepsanity check: no remaining stale references (1880, 2702, 2749, rc.1, justn-hyeok/CodeAgora)Closes #336.
🤖 Generated with Claude Code
Summary by CodeRabbit