Intent-Driven Codebase Understanding for AI-Assisted Developers
ClearCut is a VS Code extension that structures developer-agent interaction so that human judgment is exercised at every step, not bypassed. By representing codebases spatially, ClearCut helps developers rapidly build accurate mental models of AI-generated systems and identify high-risk changes.
The MVP Scope
To validate the core concept of Concentric Consequence Weighting & Spatial Judgment Forcing without premature complexity, the MVP focuses on visual layout transitions and manual tier adjustments. Full AI-driven intent capture is deferred to subsequent phases.
1. Dual Visual Layouts (Implemented & Planned)
- Folder Islands (Implemented): The default view where files flock to parent folder clusters to preserve directory hierarchy.
- Concentric Intent Rings (Planned): An alternative physics mode arranged in concentric circles representing risk/consequence tiers.
2. Concentric Risk Tiers
- Inner Circle (Critical): Core logic, high-consequence files, or files on the current task's critical path.
- Middle Circle (Supporting): Supporting utility modules and immediate dependencies of critical path files.
- Outer Circle (Cosmetic): Lower-risk, unrelated, or cosmetic files.
3. Mock/Manual Tier Assignment Control
- A sidebar control panel allowing the user to select files and manually assign them to a priority tier (Critical, Supporting, or Cosmetic). This simulates the data payload that the AI intent engine will eventually supply.
4. D3 Concentric Layout Transitions
- Switch seamlessly between the cluster force-directed layout and the radial concentric circle layout using
d3.forceRadial. - Smoothly transition node coordinates and maintain collision repulsion so circles remain readable and non-overlapping.
5. Spatial Judgment Forcing (Drag to Reassign)
- The developer can drag nodes between concentric circles.
- Repositioning a node explicitly overrides its priority level, providing a physical mechanism for human developer judgment.
Deferrals (Post-MVP Phases)
To ensure rapid validation of the visual and spatial interaction model, the following components are out of scope for the MVP:
- AI Intent Capture Engine: Natural language parsing and clarifying conversational loops to automatically map developer intent to a critical path.
- MCP Server Interface: Directly piping task context and proposed file changes from AI agents (Cursor, Claude Dev, etc.) into the extension.
- Persistent Intent History: Session tracking of file weights across window reloads.