Designing Simplicity & Taste Tools for LLMs

AST-based style analysis for nudging code generation toward boring code

The Problem

LLMs generate functionally correct code that often violates the subtle style patterns that make code maintainable. They overuse abstractions, introduce premature complexity, and miss the "boring code" wisdom that experienced developers apply instinctively.

Current approaches:

• Linting — catches syntax violations, not style wisdom
• Static analysis — measures complexity after the fact
• Manual prompting — "write simple code" is too vague to be actionable

What's missing: a tool that extracts structural style patterns from a codebase and converts them into natural language fragments that nudge LLMs toward the project's actual coding philosophy.

The Solution: Style Fragment Extraction

Scan a codebase's AST, classify structural patterns, and output natural language "style fragments" for LLM system prompts.

style_fragments:
  - "Guard clauses preferred over nested ifs (87% early-return pattern)"
  - "Error handling: check-and-return, minimal nesting (Go if-err style)"
  - "Switch/match over if-else chains (3:1 ratio)"
  - "Functions average 25 LOC, max 80 — short and focused"
  - "Single return value + error, no multi-return beyond (val, err)"
  - "Flat control flow: avg nesting depth 1.2, max 3"

These fragments go into an LLM system prompt to nudge generated code toward the codebase's actual style.

What Makes This Novel

No existing tool does this. Current AST-based tools:

• CodeRabbit — uses ast-grep patterns for code review context (closest production example)
• Annotated-AST-For-LLM — 37 stars, JS/TS only, Babel AST + AI summaries (proof of concept)
• CodeTF (Salesforce) — Tree-sitter extraction for LLM training (utility-level)
• AFT (Agent File Toolkit) — 36 stars, Rust+TS, semantic editing for AI agents (very early)

None of these: scan codebase → extract structural patterns → output natural language fragments for prompting.

Technical Architecture

                    ┌─────────────┐
                    │  Tool CLI   │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────▼─────┐ ┌───▼────┐ ┌─────▼─────┐
        │ regex      │ │ tree-  │ │ go/ast    │
        │ counter    │ │ sitter │ │ (Go only) │
        │ (baseline) │ │ (all)  │ │           │
        └─────┬──────┘ └───┬────┘ └─────┬─────┘
              │            │            │
              └────────────┼────────────┘
                           │
                    ┌──────▼──────┐
                    │  metrics +  │
                    │  style      │
                    │  fragments  │
                    └─────────────┘

Layer 1: Tree-sitter (multi-language AST)

Tree-sitter is GitHub's incremental parser with 80+ language grammars. It produces concrete syntax trees preserving all tokens.

Go bindings:

• smacker/go-tree-sitter — 548 stars, ~34 bundled grammars (Go, Rust, Python, TS, C, Java), mature
• tree-sitter/go-tree-sitter — 228 stars, official, dynamic grammar loading

Speed: ~91 SLOC/ms. A 6,000-line file parses in ~80ms. At 16 workers, 10k files × 200 LOC ≈ 1-2s.

Query language: S-expression patterns matching AST node types and fields.

;; guard clause detection
(if_statement
  consequence: (block
    (return_statement) @guard_return))

;; nested if detection
(if_statement
  consequence: (block
    (if_statement) @nested_if))

;; early return
(function_declaration
  body: (block
    (return_statement) @early_return
    (_)))

Layer 2: Pattern Classification

For each language, write Tree-sitter queries to detect structural patterns:

Layer 3: Style Fragment Generation

After classifying patterns across the codebase, generate natural language fragments:

def generate_fragments(pattern_stats):
    fragments = []

    # Guard clause preference
    if pattern_stats['guard_clause_ratio'] > 0.7:
        fragments.append(
            f"Guard clauses preferred over nested ifs "
            f"({pattern_stats['guard_clause_ratio']:.0%} early-return pattern)"
        )

    # Error handling style
    if pattern_stats['check_and_return_ratio'] > 0.8:
        fragments.append(
            "Error handling: check-and-return, minimal nesting (Go if-err style)"
        )

    # Function length
    avg_loc = pattern_stats['avg_function_loc']
    max_loc = pattern_stats['max_function_loc']
    fragments.append(
        f"Functions average {avg_loc} LOC, max {max_loc} — short and focused"
    )

    # Control flow complexity
    avg_nesting = pattern_stats['avg_nesting_depth']
    max_nesting = pattern_stats['max_nesting_depth']
    fragments.append(
        f"Flat control flow: avg nesting depth {avg_nesting:.1f}, max {max_nesting}"
    )

    return fragments

Boring Code Wisdom Integration

The tool should detect and surface boring code patterns:

• Code deletion over abstraction — Detect: unused exports, dead branches, unreferenced functions. Fragment: "Delete unused code (N unused exports, M dead branches removed in recent commits)"
• Copy before abstraction — Detect: Similar code blocks that aren't abstracted. Fragment: "Copy 2-3 times before abstracting (duplicated logic found in N places, not prematurely unified)"
• Simple-mostly-right over complex-fully-correct — Detect: Cognitive complexity per function. Fragment: "Prefer simple solutions (avg cognitive complexity: N, max: M)"
• State minimization — Detect: Stateful vs pure functions ratio. Fragment: "Minimize state (N% pure functions, state isolated to M modules)"

Implementation Roadmap

Phase 1: MVP (single language)

1. Integrate smacker/go-tree-sitter with Go grammar
2. Implement 5-6 core pattern queries (guard clause, nesting, function length)
3. Generate basic style fragments
4. CLI: tool analyze --lang=go ./src → outputs fragments as JSON

Phase 2: Multi-language

1. Add Rust, Python, TypeScript grammars
2. Language-specific pattern queries (Rust ?, Python context managers)
3. Unified fragment format across languages

Phase 3: LLM Integration

1. Auto-inject fragments into system prompts (VSCode extension, GitHub Copilot plugin)
2. Feedback loop: track generated code → measure adherence to fragments → refine queries
3. Community library of pattern queries per domain (web backends, CLIs, data pipelines)

Alternatives Considered

ast-grep

Rust CLI built on tree-sitter with 13.4k stars. Source-like pattern syntax + YAML rule combinators. More readable than S-expressions but subprocess-only (no Go library). Good secondary tool for complex rules.

rule:
  pattern: if $COND { return $VAL }
  not:
    has:
      kind: else_clause

semgrep / opengrep

Semgrep went proprietary late 2024. OpenGrep is the community fork (LGPL-2.1, 2.4k stars, 40+ languages). OCaml-based, no Go bindings. Heavier (~12s for 500k LOC Python). Overkill for style extraction — best for security rules.

Per-language native parsers

For a multi-language tool, per-language native parsers aren't practical from Go. go/ast is useful for type-aware Go-specific analysis alongside tree-sitter, but tree-sitter covers everything else.

Existing Tools Landscape

Codebase Context Extraction Tools

These tools pack codebases into AI-friendly formats but don't extract style patterns:

LLM Code Quality Evaluation Tools

Style Guidance Research

Few-shot prompting is the current state-of-the-art for style control:

• 2-5 examples influence formatting more than verbal descriptions (research)
• Example selection matters — systematic methods outperform random picks
• Combine concrete examples + explicit rules for best results

RAG for code — Retrieval-Augmented Generation retrieves relevant snippets from the codebase to inform generation (survey). Improves factual accuracy but doesn't extract or communicate style patterns explicitly.

Neural steering — Advanced research on identifying style-specific neurons and deactivating unwanted style patterns (paper). Requires fine-tuning access, not practical for most users.

The Gap This Tool Fills

Research-Backed Best Practices

Effective LLM Style Guidance (Current State)

1. Custom instructions — Define conventions once, apply to all interactions (GitHub Copilot, Claude)
2. Few-shot examples — 2-5 representative implementations showing target style
3. Explicit directives — "Follow PEP 8" + persona ("senior Python developer who writes idiomatic code")
4. Codebase context — Provide surrounding code, relevant imports, function dependencies
5. RAG retrieval — Fetch similar code from the repo to ground generation

This tool automates steps 2-4 by extracting patterns and generating both examples and directives from the actual codebase.

Measuring Adherence

Research shows effective metrics combine:

• Static analysis — Pylint scores, cognitive complexity (SonarSource)
• Human evaluation — 1-5 scales on consistency, readability, style
• LLM-as-judge — GPT-4 evaluation achieving near-human alignment
• Automated pattern detection — Variable naming consistency (userData vs user_data within functions)

Open Questions

• How to weight conflicting patterns? (e.g., 60% guard clauses, 40% nested ifs)
• Should fragments be prescriptive ("always use guard clauses") or descriptive ("guard clauses preferred 87% of time")?
• How to handle codebases with multiple styles (legacy vs new code)?
• Can we detect anti-patterns and generate negative fragments? ("Avoid deeply nested callbacks — max nesting depth is 5, should be 3")
• How do we measure if generated code actually improved? Need a feedback loop.
• Can few-shot examples be auto-selected from the codebase using AST similarity to the generation task?

Comprehensive References

AST Analysis Tools

LLM Code Quality & Evaluation

Style Guidance & Prompting Research

Codebase Context Tools

Practical Guides