The Code Review workflow performs a comprehensive quality assessment of a Roblox game’s Luau codebase. It moves through eight steps — project scan, organization review, code quality scan, architecture review, security quick-check, performance quick-check, graded report, and refactoring suggestions — culminating in an A–F grade per category and a prioritized list of improvements you can act on immediately. Use this workflow to assess a project before handing it off, to audit a game you inherited, or as a regular quality gate after shipping major features. Trigger: “Review my code”, “grade my project”, “code quality check”, “audit my scripts”, or “what’s wrong with my code”.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/brockmartin/roblox-game-skill/llms.txt
Use this file to discover all available pages before exploring further.
Project Scan
Claude maps the full project structure before reading any code.
- Full Mode
- Standard Mode
- Offline Mode
Uses
get_project_structure and get_file_tree to produce a complete source map. Records: total script count by type (Server Script, LocalScript, ModuleScript), directory organization pattern, project file format (Rojo default.project.json, Argon config, or raw .lua files), and any READMEs or documentation.Organization Review
Claude verifies that scripts are in the correct containers and that the project follows a clean, maintainable structure.Script placement rules:
Folder structure check:
| Script Type | Correct Location | Notes |
|---|---|---|
| Server Scripts | ServerScriptService | Never in ReplicatedStorage or Workspace |
| Server Modules | ServerScriptService or ServerStorage | Must not be accessible to clients |
| LocalScripts | StarterPlayerScripts, StarterCharacterScripts, or StarterGui | Purpose determines location |
| Shared Modules | ReplicatedStorage | Used by both server and client |
| Client-only Modules | ReplicatedStorage or StarterPlayerScripts | Must contain no server logic |
- Are scripts organized into logical folders (
Services/,Controllers/,Components/,UI/)? - Is there a consistent naming convention (PascalCase for modules, camelCase for variables)?
- Are related scripts grouped together or scattered randomly?
- Scripts directly in
Workspace(runs on server but visible in the hierarchy to exploiters) ModuleScriptinReplicatedFirstwithout a clear justification- Server logic in
ReplicatedStorage(accessible to any client) - Orphaned scripts not parented to an executing container (they will never run)
Code Quality Scan
Claude scans for deprecated APIs, anti-patterns, and code quality issues.Deprecated APIs:
Anti-patterns:
Example: before and after a quality passIn Full/Standard modes,
| Pattern | Replacement | Severity |
|---|---|---|
wait( | task.wait( | Medium |
spawn( | task.spawn( | Medium |
delay( | task.delay( | Medium |
coroutine.wrap / coroutine.resume in most use cases | task.spawn / task.defer | Low |
| Pattern | Issue | Fix |
|---|---|---|
Global variables (missing local) | Pollutes _G, causes subtle bugs | Always use local |
| Missing type annotations | No Luau type checking, reduced readability | Add : type to function signatures |
String .. concatenation in loops | Creates garbage per iteration | Use table.concat or string buffers |
Instance.new("X") then .Parent = Y as separate statements in hot paths | Two replication events per creation | Set parent last after all properties, or pass parent as the second argument |
Nested WaitForChild chains | Fragile and thread-blocking | Cache references at initialization |
pcall with no error handling | Silently swallows failures | Log or handle: local ok, err = pcall(...) |
| Magic numbers | Unclear intent | Extract into named constants |
grep_scripts runs a pass for each anti-pattern. In Offline mode, Claude reviews each pasted script manually.Architecture Review
Claude evaluates module boundaries, dependency direction, circular requires, and event communication patterns.Clean module pattern:Dependency direction — Dependencies must flow one way: Scripts → Modules, not Modules → Scripts. Higher-level modules depend on lower-level modules.Circular require detection — Claude searches for
require() chains where Module A requires Module B which requires Module A. Circular requires cause initialization order bugs in Roblox that are very difficult to trace. The fix is to extract shared logic into a third module or use dependency injection.Event architecture — Claude evaluates whether inter-module communication uses direct requires, events, or a message bus, and whether the pattern is consistent across the codebase.Security Quick-Check
A focused security scan. For a full audit, use the Security Audit workflow.Claude searches for
OnServerEvent:Connect and OnServerInvoke handlers and checks whether each one validates argument types before use. Client scripts are scanned for patterns that indicate the client is authoritative over server state.| Severity | Pattern |
|---|---|
| Critical | Unvalidated remote that modifies currency, inventory, or stats |
| High | Client-computed damage or rewards sent to server |
| Medium | Missing type checks on non-critical remotes |
| Low | Missing cooldowns on low-impact remotes |
Performance Quick-Check
A focused performance scan. For a full audit, use the Performance Audit workflow.Claude counts
RunService.Heartbeat:Connect() calls across all scripts and flags handlers that do heavy work (raycasting, table iteration, Instance queries) on every frame. It also checks for :Connect( calls where the connection is not stored, PlayerAdded handlers that create connections without cleanup in PlayerRemoving, and Instance.new without a corresponding :Destroy() path.| Severity | Pattern |
|---|---|
| Critical | Unbounded memory growth (leaking connections per player join) |
| High | Multiple expensive Heartbeat handlers |
| Medium | Deprecated API usage in hot paths |
| Low | Uncached GetService calls |
Quality Report
Claude compiles all findings into a graded quality report.Grading rubric:
| Grade | Description |
|---|---|
| A | Excellent. Clean architecture, no deprecated APIs, proper validation, good module boundaries. Minor suggestions only. |
| B | Good. Mostly clean with some deprecated API usage or minor organizational issues. No security or performance problems. |
| C | Acceptable. Functional but has notable code quality issues, some architectural concerns, or minor security gaps. Needs improvement before scaling. |
| D | Poor. Significant issues: deprecated APIs throughout, weak architecture, security vulnerabilities, or performance problems. Requires substantial refactoring. |
| F | Critical. Major security vulnerabilities, memory leaks, no validation on remotes, or fundamental architectural problems that will cause failures at scale. |
Refactoring Suggestions
Claude provides actionable refactoring recommendations, ordered by impact.
For each suggestion, Claude provides:
Quick Wins (under 30 minutes each)
Quick Wins (under 30 minutes each)
- Replace deprecated APIs:
wait()→task.wait(),spawn()→task.spawn(),delay()→task.delay() - Cache
GetService()calls at the top of each script as local variables - Add type annotations to function signatures
- Replace magic numbers with named constants in a shared
Constantsmodule - Fix
Instance.newparent-last pattern in hot paths
Structural Improvements (1–3 hours each)
Structural Improvements (1–3 hours each)
- Extract duplicate code blocks into shared ModuleScripts
- Reorganize scripts into correct containers (server logic out of ReplicatedStorage)
- Add validation to unprotected RemoteEvent handlers
- Disconnect leaked event connections in
PlayerRemovingandCharacterAddedcleanup - Break up scripts over 300 lines into focused, single-responsibility modules
Architectural Changes (half-day to multi-day)
Architectural Changes (half-day to multi-day)
- Introduce a service/controller architecture pattern for the server layer
- Implement dependency injection to resolve circular
require()chains - Add a centralized event/message bus for cross-system communication
- Implement a data layer abstraction over raw
DataStorecalls - Add a state management pattern for complex, shared game state
- What to change
- Why it matters (impact on maintainability, performance, or security)
- How to implement it (specific code example or refactoring pattern)
- Effort estimate (quick win / moderate / significant)
For the complete Luau style guide, type annotation patterns, and module architecture reference used in this workflow’s grading criteria, see Luau Mastery and Architecture Patterns.