Code Audit

Perform comprehensive code audits and generate structured markdown reports.

Codex note: This skill references Claude Code subagents (Task(...)). In Codex, run the equivalent steps with tool calls (for example functions.shell_command and multi_tool_use.parallel) or run them sequentially. See ../../COMPATIBILITY.md.

Workflow

1. •Scope: Determine target (full repo, specific path, or focused concern)
2. •Discovery: List and categorise source files
3. •Analysis: Evaluate each category systematically
4. •Report: Generate markdown report using template format
5. •GitHub Issues: Create issues using scripts/create_issue.sh:
   • •First: Create individual issues for each actionable recommendation
   • •Then: Create the full audit report with subtasks linking to each issue

Time Estimates

For large projects, consider:

• •Auditing by module/package
• •Focusing on specific concerns (security-only, performance-only)
• •Auditing recently changed files only

Analysis Categories

Severity Levels

Scoring

Rate each applicable category out of 10:

• •Architecture, Thread Safety, Error Handling
• •DRY Compliance, SOLID Compliance
• •Security, Performance, Testability

Overall score: weighted average (bugs and security weighted higher).

Security-Focused Audit

When focusing on security, prioritise:

1. •

   Input Validation

   • •User input sanitisation
   • •SQL/NoSQL injection vectors
   • •Command injection risks
   • •Path traversal vulnerabilities
2. •

   Authentication & Authorisation

   • •Session management
   • •Token handling
   • •Permission checks
   • •Privilege escalation paths
3. •

   Data Protection

   • •Credential storage
   • •Sensitive data exposure
   • •Encryption usage
   • •Logging of sensitive data
4. •

   Dependencies

   • •Known vulnerabilities (CVEs)
   • •Outdated packages
   • •Typosquatting risks

Report Format

See references/report-template.md for the exact output structure.

Key formatting rules:

• •Two-column tables for issue metadata (severity, location, impact, recommendation)
• •Code blocks with language hints for all code examples
• •Horizontal rules between major sections
• •ASCII diagrams in code blocks for architecture
• •Summary statistics table at the end
• •Prioritised recommendations (P0/P1/P2/P3)
• •Never use em-dashes

Output

Step 1: Create Individual Recommendation Issues

For each actionable recommendation, create a separate issue using the format in references/issue-template.md. Capture the returned issue URL for each.

bash scripts/create_issue.sh \
  --project "[Project Name]" \
  --title "[Brief issue title]" \
  --label "code-audit,priority:[level],[category]" \
  --body "$ISSUE_BODY"

Priority labels:

• •P0/Critical: priority:critical
• •P1/High: priority:high
• •P2/Medium: priority:medium
• •P3/Low: priority:low

Category labels (use as appropriate):

• •security, performance, bug, technical-debt
• •architecture, observability, testing, documentation

Step 2: Create Full Audit Report with Subtasks

Append a "Related Issues" section to the full report with subtasks linking to each individual issue:

## Related Issues

- [ ] #123 - Fix race condition in data index map
- [ ] #124 - Add thread safety to RedisClient
- [ ] #125 - Extract side validation utility
- [ ] #126 - Add metrics and observability

Then create the main audit issue:

bash scripts/create_issue.sh \
  --project "[Project Name]" \
  --title "Code Audit Report - [Project] - [Date]" \
  --label "code-audit" \
  --body "$FULL_REPORT_WITH_SUBTASKS"

With a specific repository, add --repo "owner/repo".

When to Split Audits

Create separate audit reports when:

• •Different parts of the codebase have different owners
• •Findings span multiple priority levels with different timelines
• •The report exceeds ~500 lines (becomes hard to track)

Confirm all issue URLs with the user after creation.

Subagent Usage

Use subagents to parallelize analysis and reduce main context bloat.

Phase 2: Parallel Analysis

For medium to large codebases, launch up to 4 Explore agents in parallel to analyze different categories simultaneously:

Launch parallel Explore agents:

1. Architecture Agent:
   "Analyze the codebase architecture. Look for:
   - Separation of concerns violations
   - Circular dependencies
   - Component structure issues
   - Coupling problems between modules
   Return: List of findings with file:line references and severity"

2. Security Agent:
   "Perform security analysis. Scan for:
   - Input validation gaps (SQL injection, XSS, command injection)
   - Credential handling issues (hardcoded secrets, improper storage)
   - Authentication/authorization flaws
   - OWASP Top 10 vulnerabilities
   Return: List of findings with file:line references and severity"

3. Performance Agent:
   "Analyze performance issues. Find:
   - O(n²) or worse algorithms
   - Unnecessary object copies or allocations
   - N+1 query patterns
   - Missing caching opportunities
   - Inefficient data structures
   Return: List of findings with file:line references and severity"

4. Code Quality Agent:
   "Check code quality and best practices. Look for:
   - SOLID principle violations (god classes, tight coupling)
   - DRY violations (duplicated logic, copy-paste code)
   - Magic numbers and missing documentation
   - Broad exception handling
   - Resource leaks
   Return: List of findings with file:line references and severity"

Each agent returns structured findings. Main context synthesizes into final report.

Benefits:

• •4x faster analysis on large codebases
• •Exploration output stays in subagent context (reduces token usage)
• •Main context receives only synthesized findings

Phase 5: Background Issue Creation

After generating the report, create GitHub issues in background:

Launch background agent:
"Create GitHub issues for each audit finding using scripts/create_issue.sh.
Findings to create:
[List of findings with titles, labels, and bodies]

For each finding:
1. Create issue with appropriate labels (priority:X, category)
2. Capture the issue URL
3. Return all created issue URLs when complete"

Main context can continue summarizing results while issues are created.

When to use subagents:

• •Codebase > 5,000 LOC: Use parallel analysis agents
• •More than 5 issues to create: Use background issue creation
• •Time-sensitive audit: Always use parallel agents

When to skip subagents:

• •Single file audit
• •Focused audit on specific concern (one category only)
• •Small codebase < 1,000 LOC

Related Skills

• •race-condition-audit: Deep-dive on concurrency issues
• •fix-github-issue: Implement fixes from audit recommendations