Skip to main content

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.

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”.
1

Project Scan

Claude maps the full project structure before reading any code.
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.
2

Organization Review

Claude verifies that scripts are in the correct containers and that the project follows a clean, maintainable structure.Script placement rules:
Script TypeCorrect LocationNotes
Server ScriptsServerScriptServiceNever in ReplicatedStorage or Workspace
Server ModulesServerScriptService or ServerStorageMust not be accessible to clients
LocalScriptsStarterPlayerScripts, StarterCharacterScripts, or StarterGuiPurpose determines location
Shared ModulesReplicatedStorageUsed by both server and client
Client-only ModulesReplicatedStorage or StarterPlayerScriptsMust contain no server logic
Folder structure check:
  • 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?
Red flags:
  • Scripts directly in Workspace (runs on server but visible in the hierarchy to exploiters)
  • ModuleScript in ReplicatedFirst without a clear justification
  • Server logic in ReplicatedStorage (accessible to any client)
  • Orphaned scripts not parented to an executing container (they will never run)
3

Code Quality Scan

Claude scans for deprecated APIs, anti-patterns, and code quality issues.Deprecated APIs:
PatternReplacementSeverity
wait(task.wait(Medium
spawn(task.spawn(Medium
delay(task.delay(Medium
coroutine.wrap / coroutine.resume in most use casestask.spawn / task.deferLow
Anti-patterns:
PatternIssueFix
Global variables (missing local)Pollutes _G, causes subtle bugsAlways use local
Missing type annotationsNo Luau type checking, reduced readabilityAdd : type to function signatures
String .. concatenation in loopsCreates garbage per iterationUse table.concat or string buffers
Instance.new("X") then .Parent = Y as separate statements in hot pathsTwo replication events per creationSet parent last after all properties, or pass parent as the second argument
Nested WaitForChild chainsFragile and thread-blockingCache references at initialization
pcall with no error handlingSilently swallows failuresLog or handle: local ok, err = pcall(...)
Magic numbersUnclear intentExtract into named constants
Example: before and after a quality pass
-- BEFORE: multiple quality issues
function giveCurrency(player, amount)
    wait(0.1)
    local data = game:GetService("DataService").getData(player)
    data.coins = data.coins + amount
    player.leaderstats.Coins.Value = data.coins
end

-- AFTER: task library, cached service, type annotations, nil guards
local DataService = require(ServerStorage.Services.DataService)

local function giveCurrency(player: Player, amount: number): ()
    task.wait(0.1)
    local data = DataService.getData(player)
    if not data then return end
    data.coins += amount

    local leaderstats = player:FindFirstChild("leaderstats")
    local coinsValue  = leaderstats and leaderstats:FindFirstChild("Coins")
    if coinsValue then coinsValue.Value = data.coins end
end
In Full/Standard modes, grep_scripts runs a pass for each anti-pattern. In Offline mode, Claude reviews each pasted script manually.
4

Architecture Review

Claude evaluates module boundaries, dependency direction, circular requires, and event communication patterns.Clean module pattern:
-- GOOD: Single responsibility, clean public API
local InventoryService = {}

function InventoryService.addItem(player: Player, itemId: string, quantity: number): boolean
    -- implementation
    return true
end

function InventoryService.removeItem(player: Player, itemId: string, quantity: number): boolean
    -- implementation
    return true
end

return InventoryService
Dependency direction — Dependencies must flow one way: Scripts → Modules, not Modules → Scripts. Higher-level modules depend on lower-level modules.
ServerScript (entry point)
  → GameService (orchestration)
    → InventoryModule (domain logic)
      → DataModule (persistence)
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.
5

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.
SeverityPattern
CriticalUnvalidated remote that modifies currency, inventory, or stats
HighClient-computed damage or rewards sent to server
MediumMissing type checks on non-critical remotes
LowMissing cooldowns on low-impact remotes
6

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.
SeverityPattern
CriticalUnbounded memory growth (leaking connections per player join)
HighMultiple expensive Heartbeat handlers
MediumDeprecated API usage in hot paths
LowUncached GetService calls
7

Quality Report

Claude compiles all findings into a graded quality report.Grading rubric:
GradeDescription
AExcellent. Clean architecture, no deprecated APIs, proper validation, good module boundaries. Minor suggestions only.
BGood. Mostly clean with some deprecated API usage or minor organizational issues. No security or performance problems.
CAcceptable. Functional but has notable code quality issues, some architectural concerns, or minor security gaps. Needs improvement before scaling.
DPoor. Significant issues: deprecated APIs throughout, weak architecture, security vulnerabilities, or performance problems. Requires substantial refactoring.
FCritical. Major security vulnerabilities, memory leaks, no validation on remotes, or fundamental architectural problems that will cause failures at scale.
## Code Review Report

### Overall Grade: [A–F]

### Organization: [A–F]
- [Findings with file paths and specific issues]

### Code Quality: [A–F]
- [Findings by severity]

### Architecture: [A–F]
- [Findings with dependency diagrams if relevant]

### Security: [A–F]  (quick-check)
- [Findings with severity]

### Performance: [A–F]  (quick-check)
- [Findings with severity]

### Summary Statistics
- Total scripts reviewed:       X
- Deprecated API usages:        X
- Unvalidated remotes:          X
- Potential memory leaks:       X
- Circular dependencies:        X
- Duplicate code instances:     X

### Top 5 Priority Fixes
1. [Most impactful fix with specific code suggestion]
2. ...
8

Refactoring Suggestions

Claude provides actionable refactoring recommendations, ordered by impact.
  • 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 Constants module
  • Fix Instance.new parent-last pattern in hot paths
  • 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 PlayerRemoving and CharacterAdded cleanup
  • Break up scripts over 300 lines into focused, single-responsibility modules
  • 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 DataStore calls
  • Add a state management pattern for complex, shared game state
For each suggestion, Claude provides:
  1. What to change
  2. Why it matters (impact on maintainability, performance, or security)
  3. How to implement it (specific code example or refactoring pattern)
  4. Effort estimate (quick win / moderate / significant)
If MCP write access is available, Claude offers to apply all Quick Win fixes directly.
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.

Build docs developers (and LLMs) love