Setting the file. One moment.
Chapter 56 · Reviewing Claude Config
Subchapter 56.2
reference/priority-framework.mdMarkdown8 KBView on GitHub
Classification system for prioritizing issues found in Claude configuration files.
Definition: Issues that prevent functionality, expose security vulnerabilities, or cause immediate harm.
Examples:
Action Required: Must fix immediately before approval.
Review Comment Format:
**CRITICAL**: [Issue description]
[Specific fix with code example]
This must be fixed before approval because [security/functionality reason].Definition: Issues that significantly impact quality, maintainability, or user experience but don’t prevent basic functionality.
Examples:
Action Required: Should fix in this PR/commit. If time-constrained, create follow-up issue.
Review Comment Format:
**IMPORTANT**: [Issue description]
[Specific recommendation]
[Rationale explaining why this matters]Definition: Improvements that enhance quality but aren’t essential for approval.
Examples:
Action Required: Optional improvements. Consider for future work.
Review Comment Format:
**SUGGESTED**: [Improvement suggestion]
[What would be better and why]
This would improve [aspect] but isn't required for approval.Definition: Personal preferences, alternative approaches, or minor stylistic choices.
Examples:
Action Required: Author decides. No expectation to change.
Review Comment Format:
**OPTIONAL**: [Observation or suggestion]
[Alternative approach if applicable]
This is a personal preference - feel free to keep current approach.Use this structured thinking approach to classify issues:
Does this significantly impact quality, maintainability, or UX? → YES: IMPORTANT → NO: Continue
Would this improve quality but not essential? → YES: SUGGESTED → NO: OPTIONAL
In security-sensitive configurations (settings.json, permissions):
For skills intended for marketplace:
For internal-only configurations:
| Issue | Priority |
|---|---|
| Committed settings.local.json | CRITICAL |
| Hardcoded API keys/tokens | CRITICAL |
| Dangerous auto-approved commands | CRITICAL |
| Overly broad permissions (Read://, Write://) | CRITICAL |
| Permissions exposing ~/.ssh, /etc | CRITICAL |
| Permissions broader than needed | IMPORTANT |
| Issue | Priority |
|---|---|
| Missing YAML frontmatter | CRITICAL |
| Broken file references | CRITICAL |
| File > 500 lines without progressive disclosure | IMPORTANT |
| Poor file organization | SUGGESTED |
| Missing structured thinking blocks | IMPORTANT |
| Issue | Priority |
|---|---|
| Vague or unclear instructions | IMPORTANT |
| Missing examples for complex concepts | IMPORTANT |
| No activation triggers in description | IMPORTANT |
| Duplicated documentation | IMPORTANT |
| Inefficient token usage | SUGGESTED |
| Additional examples would help | SUGGESTED |
| Alternative phrasing | OPTIONAL |
| Issue | Priority |
|---|---|
| Invalid JSON syntax | CRITICAL |
| Malformed YAML frontmatter | CRITICAL |
| Incorrect field names | IMPORTANT |
| Missing required fields | IMPORTANT |
| Deprecated fields | SUGGESTED |
When multiple issues exist in a single review:
Example 1: Security Issue
❌ settings.json:5 - settings.local.json committed to git Priority: CRITICAL Rationale: Exposes potentially sensitive user-specific configuration and API keys.
Example 2: Structure Issue
❌ skill.md:1 - Missing YAML frontmatter Priority: CRITICAL Rationale: Skill won’t be recognized by Claude Code without frontmatter.
Example 3: Quality Issue
❌ skill.md:3 - Description lacks activation triggers Priority: IMPORTANT Rationale: Users won’t know when to invoke this skill. Reduces discoverability.
Example 4: Improvement Suggestion
❌ checklist.md:45 - Could add more examples Priority: SUGGESTED Rationale: Additional examples would clarify complex concept, but current instruction is functional.
Example 5: Style Preference
❌ skill.md:12 - Alternative phrasing possible Priority: OPTIONAL Rationale: Current phrasing is clear, alternative is just personal preference.