Agent

DocsAgentCode Order

Analyze folder structure and file sizes to bring order to your codebase. Generates a cleanup report with oversized files, deep nesting, empty folders, and consolidation opportunities.

Code Order

The Code Order extension gives the agent a read-only structural analysis of your project. A single tool — code_order_report — scans the directory tree and returns a Markdown cleanup report. The agent uses this report as input to deduce what to split, flatten, or reorganize.

What It Does

It walks your project's folder tree (respecting .git, node_modules, dist, and other build artifacts) and computes:

  • File & folder counts, total size, max depth
  • Oversized source files — text files over 100 KB (binary/media are skipped)
  • Deep nesting — directories deeper than 8 levels
  • Empty folders — directories containing no files recursively
  • Empty files — zero-byte files
  • Single-child folders — candidates for flattening into their parent
  • Duplicate sibling folder names — accidental parallel structure
  • Top 15 largest files and the extension distribution

The output is a structured Markdown report returned directly into the session. The agent reads it and decides what to act on — Code Order never modifies files itself.

Usage

code_order_report {
  path: "." // optional — defaults to the current working directory
}

No other parameters. No configuration files. No environment variables.

Always-On Structural Discipline

Independent of this extension, the Spectral system prompt enforces a tree-like directory structure rule whenever the agent creates new files:

  • Place files in semantically meaningful subdirectories, not at the project root
  • Group related files into dedicated folders (handlers/auth/, utils/string/)
  • Prefer feature/module/file.ts over feature-file.ts at root
  • Keep folder depth reasonable (max 5–6 levels), but prefer nesting over flattening

This rule is always active — it improves LLM navigability and agentic coding efficiency, even if the Code Order extension is disabled.

Typical Workflows

Before a Refactor

"Run code_order_report on the backend and tell me what to clean up first."

The agent calls the tool, reads the report, and proposes concrete reorganization steps (split this oversized file, flatten this deep path, remove these empty folders).

Periodic Health Check

"Analyze the whole project structure — anything structurally wrong?"

The report surfaces deep nesting, single-child folders, and duplicate sibling names that accumulate over time in growing codebases.

What It Does Not Do

  • It does not modify, move, or delete files — it is strictly read-only.
  • It does not require configuration — sensible defaults are hardcoded.
  • It does not analyze code content — only structure and file sizes.
  • It does not flag binary/media files as oversized — only source files.

Ignored Directories

The walker skips common build, dependency, and tooling directories automatically: node_modules, .git, dist, dist-release, build, .next, coverage, __pycache__, .venv, target, out, .logs, and more.