File Review System Instructions for Claude Code

Purpose

Help the repository owner identify potential issues, inconsistencies, and areas for improvement
Document questions and concerns that may require clarification or refactoring
Provide a comprehensive review of code quality and architectural decisions
Read and understand Explanatory Files (if present) to learn about code rationales and implementation decisions before raising questions

Starting Point

The LLM should walk through all directories recursively from the specified starting path or $ARGUMENTS
Treat the specified path as the root of the review scope
The review starts from a specified path, which may or may not be the repository root

File Relationships

Explanatory Files: Files with md extension: Owner-provided file containing explanations and rationales for code implementation decisions, such as README.md and CLAUDE.md. However, QUESTIONS.md is not considered an Explanatory File
- Scope: Covers files in its directory AND all subdirectories recursively
- May contain responses to specific questions by referencing Question IDs from QUESTIONS.md files
- Acts as a knowledge base for design decisions and implementation rationales
- Can exist at any directory level (root or subdirectories)
- Inheritance: When checking for explanations, look up through the directory hierarchy
QUESTIONS.md: File you create/update to list issues, questions, and concerns with unique IDs
- Scope: Only covers files directly in its directory (not subdirectories)
- Create one QUESTIONS.md file in EACH directory that contains code files
- Questions must maintain stable IDs so they can be referenced from any of Explanatory Files
- Existing question IDs must never be changed when updating the file

Critical ID Management

When updating QUESTIONS.md: First read both Explanatory Files and existing QUESTIONS.md to identify which Question IDs are already in use and potentially referenced
Preserve existing IDs: Never change IDs of existing questions, as any of Explanatory Files may reference them
Check for answers: If an Explanatory File references a Question ID with an explanation, evaluate whether the explanation is satisfactory. If the explanation fully addresses the concern, remove the question from QUESTIONS.md. If the explanation is unclear, incomplete, or raises additional concerns, keep the question and append a note explaining why the provided answer is insufficient (e.g., "Note: README.md addresses this but the explanation about X is unclear because Y"). However, if an Explanatory File indicates to ignore the concern, remove the question in this case.
New questions only: Only add new questions with new IDs for issues not already listed and not explained in any Explanatory Files.

Methodology

Initial File Check
- Explanatory Files lookup (hierarchical search):
  - Check if Explanatory Files exist in the current directory
  - Also check ALL parent directories up to the specified starting path for Explanatory Files
  - Read all found Explanatory Files thoroughly, as they may contain explanations for files in the current directory
  - Remember: An Explanatory File in a parent directory can explain files in any of its subdirectories
- QUESTIONS.md check (local only):
  - Check if QUESTIONS.md exists in the current directory only
  - Read all existing questions and their IDs
- Note which Question IDs are referenced in any Explanatory Files as already answered
Directory-by-Directory Processing
- Start from the specified path (not necessarily the repository root)
- Process each directory recursively from the starting point
- For each directory:
  - Only create QUESTIONS.md if the directory contains code files directly (not in subdirectories)
  - If a directory only contains subdirectories (no files), do NOT create QUESTIONS.md
  - Analyze all code files within that specific directory (not subdirectories)
  - Questions in each QUESTIONS.md should only reference files directly in that directory
- Continue recursively into all subdirectories
- Exclude directories and files as specified:
  - Binary files and common ignore patterns
  - Files whose names start with "_" (e.g., _temp.js, _backup.py)
  - Directories named "obsolete", "obsoletes", "to_be_removed", "archived", "deprecated", "tmp", "temporary", "reserved", "backup", or similar
Examples of ignored paths:
- _temp.js, _backup.py (files starting with underscore)
- /obsolete/old-code.js, /to_be_removed/legacy.py (deprecated directories)
- /archived/, /deprecated/ (similar obsolete directory names)
File-by-File Analysis Within Each Directory
- Read each code file and text files in the current directory only
- Never try to run the code file to analyze
- Analyze code structure, logic, and implementation details
- Before identifying an issue:
  - Check if this issue already exists in the current directory's QUESTIONS.md
  - Check ALL Explanatory Files in the directory hierarchy (current directory and all parent directories up to the starting path) for explanations
  - An Explanatory File in any parent directory may explain design decisions for the current file
  - Check if any Explanatory File has answered an existing question about this issue
- Only raise new questions for issues NOT already documented or explained in any applicable Explanatory Files
Documentation Generation Per Directory
- Only create/update QUESTIONS.md in directories that directly contain code files
- Never create QUESTIONS.md in directories that only contain subdirectories
- Each QUESTIONS.md covers only the files directly in its directory (not in subdirectories)
- Update (never recreate from scratch) existing QUESTIONS.md files
- Preserve all existing questions and their IDs (unless satisfactorily answered)
- Append new questions with new unique IDs
- Maintain a clear, organized structure for easy navigation
- IMPORTANT: Delete QUESTIONS.md files when no questions remain:
  - If all existing questions have been answered satisfactorily in any Explanatory Files, delete the file
  - If no new questions are found and no existing questions remain, delete the file
  - If a directory has no code files directly in it, do not create QUESTIONS.md

Question Guidelines

Scope of Questions

Questions should cover a wide range of concerns, including but not limited to:

Code Quality: Unclear variable names, complex logic, code smells
Architecture: Design patterns, coupling issues, scalability concerns
Security: Potential vulnerabilities, unsafe practices
Performance: Inefficient algorithms, resource usage
Maintainability: Documentation gaps, test coverage, technical debt
Best Practices: Deviation from language/framework conventions

Question Format

Each question entry should include:

Question ID: Unique 4-character alphanumeric ID with category prefix
- Format: [CATEGORY]-[A-Z0-9]{4} (e.g., SEC-X73D, PERF-B9K2)
- Categories: SEC (Security), PERF (Performance), ARCH (Architecture), MAINT (Maintainability), BUG (Potential Bug), QUAL (Code Quality)
- Must be unique within the entire repository (across all QUESTIONS.md files)
- CRITICAL: Keep the same IDs for existing questions when updating the file
- Never reuse IDs when adding new questions
- IDs enable cross-referencing between Explanatory Files and QUESTIONS.md
File Reference: Specify the exact file name (no path needed as questions are in the same directory)
Line Numbers: Include specific line numbers when applicable (update when necessary)
Context: Brief description of the code section in question (with class name, function name, method name and so on if applicable)
Question/Concern: Clear articulation of the issue or uncertainty
Impact Level: High/Medium/Low priority indicator
Confidence: High/Medium/Low
- High: Definitely an issue
- Medium: Likely an issue, needs verification
- Low: Possibly intentional, seeking clarification

Additional Optional Fields:

Code Snippet: Include relevant code (max 10 lines) when it helps clarify the issue
Suggested Approach: Propose potential solutions when appropriate
Related Files: List other files affected by or related to this issue (within the same directory)

Example Format:

## Questions for [Current Directory Name]
Total questions: 2

### ID: SEC-X73D
**File**: `validator.js` (Lines 45-52)
**Timestamp**: 2025-06-14 12:34
**Context**: Password validation function
**Question**: The regex pattern appears to allow passwords without special characters. Is this intentional, or should the security requirements be stricter?
**Impact**: Medium - Security consideration
**Confidence**: High
**Code Snippet**:
```javascript
if (password && password.length > 8) {
    return true;
}

Suggested Approach: Consider using a regex pattern that enforces special characters, numbers, and mixed case


### ID: ARCH-B9K2
**Directory-wide Concern**
**Timestamp**: 2025-06-14 12:35
**Context**: Error handling pattern
**Question**: There's inconsistent error handling across files in this directory - some use try-catch, others use .catch(), and some have no error handling. Should we establish a standard pattern?
**Impact**: High - Code consistency and reliability
**Confidence**: High
**Related Files**:
- `user.js`
- `auth.js`
- `database.js`

Important Constraints

Read-Only Operation: Do NOT modify any existing code files or Explanatory Files
Non-Destructive Updates: Only update (never recreate) QUESTIONS.md files
Directory Isolation: Each QUESTIONS.md should only contain questions about files in its own directory
Preserve Existing Content: Keep all existing questions and their IDs intact unless they have been satisfactorily answered in Explanatory Files
Maintain ID Stability: Never change existing Question IDs as they may be referenced in Explanatory Files
Respect Existing Documentation: If an Explanatory File explains a design decision or answers a question satisfactorily, or indicates to ignore a concern, accept it
Clean Up Empty Files: Delete QUESTIONS.md files that have no remaining questions (either because all were answered or no issues were found)

Output Requirements

Create/update one QUESTIONS.md per directory that directly contains code files with questions
Do not create QUESTIONS.md in directories that only contain subdirectories
Each directory's QUESTIONS.md should only reference files directly in that directory (not in subdirectories)
Delete QUESTIONS.md files when they become empty:
- If all questions are answered satisfactorily, delete the file
- If no questions exist for a directory, do not create/keep the file
Include a summary count at the top of each file (e.g., "Total questions: 12")
Sort the questions by file name and line number
Use clear markdown formatting for readability
Include timestamps showing when the code file being questioned was last modified (format: YYYY-MM-DD HH:mm)
Ensure all new questions have unique IDs that don't conflict with existing ones across the entire review scope

Best Practices

Process each directory independently for QUESTIONS.md: Create separate QUESTIONS.md files for each directory
Check ALL applicable Explanatory Files: When analyzing a file, check Explanatory Files in the current directory and ALL parent directories
Understand scope differences:
- Explanatory Files: Covers its directory and ALL subdirectories recursively
- QUESTIONS.md: Covers ONLY files directly in its directory
Always read Explanatory Files hierarchically before analyzing any files
Never modify existing Question IDs as they create a stable reference system
Check for answered questions: Evaluate Explanatory File explanations (from any level of the hierarchy) and remove questions that are satisfactorily answered or marked to ignore
Be constructive and specific in your questions
Avoid being overly pedantic about style preferences
Focus on issues that impact functionality, maintainability, or security
When uncertain if something is intentional, check documentation first
Only add genuinely new questions not already covered
Generate IDs that are easy to reference but unlikely to collide with existing ones
Include code snippets when they help clarify the issue
Suggest solutions when you have constructive recommendations
Accept documented rationales in Explanatory Files, including directives to ignore specific concerns
When you find comments in a language other than English, write QUESTIONS.md in that language.

Directory Structure Example

Starting from a specified path /project/src/:

src/  (starting point - not necessarily repository root)
├── CLAUDE.md (covers explanations for ALL files under src/, including subdirectories)
├── QUESTIONS.md (only contains questions about main.js)
├── main.js
├── utils/  (no QUESTIONS.md here - only contains subdirectories)
│   ├── TODO.md (covers explanations for auth/ and helpers/ subdirectories)
│   ├── auth/
│   │   ├── QUESTIONS.md (only contains questions about login.js and validator.js)
│   │   ├── login.js
│   │   └── validator.js
│   └── helpers/
│       ├── QUESTIONS.md (only contains questions about format.js)
│       └── format.js
└── components/  (no QUESTIONS.md here - no files directly in this directory)
    └── ui/
        ├── README.md (covers explanations for all files in ui/)
        ├── QUESTIONS.md (only contains questions about button.js and modal.js)
        ├── button.js
        └── modal.js

Key Points:

Explanatory File scope: Each Explanatory File can explain files in its directory AND all subdirectories
- Example: /src/CLAUDE.md can explain issues in /src/utils/auth/login.js
QUESTIONS.md scope: Only contains questions about files directly in its directory
- Example: /src/utils/auth/QUESTIONS.md only questions login.js and validator.js
When checking for explanations, look up through ALL parent Explanatory Files
The starting path can be any directory, not necessarily the repository root

fanannan/quest.md

Select an option

No results found