Build an Autonomous Coding Agent · 45 min · Python · tree-sitter · tree-sitter-python

Codebase Understanding Layer

The file relevance scorer is the single biggest quality lever in this entire agent -- skip it and every later lesson inherits the failure.

Hiring signal: AST-level code understanding and relevance scoring is exactly the layer that separates a coding agent that works on toy examples from one that works on your actual, medium-sized codebase.

What you will learn

Parse Python source into an AST with tree-sitter and extract function/class signatures
Build a repo-wide structural summary without including full file contents
Score files by relevance to a task description and budget context accordingly

Introduction

This is the lesson the SPEC's own hotspot list flags first: skip the file relevance scorer, and every later lesson inherits a context-window problem you'll fight for the rest of the course. Today you build it properly.

AST parsing: signatures, not full source

import tree_sitter_python as tspython
from tree_sitter import Language, Parser

PY_LANGUAGE = Language(tspython.language())
parser = Parser(PY_LANGUAGE)

def extract_signatures(source_code: str) -> list[str]:
    tree = parser.parse(bytes(source_code, "utf8"))
    signatures = []

    def walk(node):
        if node.type in ("function_definition", "class_definition"):
            name_node = node.child_by_field_name("name")
            if name_node:
                signatures.append(f"{node.type}: {name_node.text.decode()}")
        for child in node.children:
            walk(child)

    walk(tree.root_node)
    return signatures

Notice this extracts function and class NAMES from the AST, not their bodies -- a 200-line file might reduce to 8 signature lines. This is the actual trick behind every "codebase understanding" feature you've seen in Claude Code or Cursor: the agent's first pass over a repo doesn't need full source, it needs a structural map (what functions/classes exist, where) accurate enough to decide which files are worth reading in full.

The tree-sitter Python bindings API changed recently -- verify before trusting older tutorials
Language(tspython.language()) and Parser(PY_LANGUAGE) (language passed to the constructor) is the current pattern as of tree-sitter 0.26.x. Older tutorials show Parser() then parser.set_language(PY_LANGUAGE) as two separate steps -- that's a previous version's API. If a code snippet you find online doesn't match what you see in pip show tree-sitter's version, don't assume it's still correct; check the current docs. This is the exact "your training data is likely wrong" caution baked into how this course was written.

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers Relevance scoring: ranking files against a task, not just listing them, What You're Building — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.