Skip to content

Instantly share code, notes, and snippets.

@realgenekim

realgenekim/chromium-michael-feathers.md

Created April 5, 2026 04:24
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save realgenekim/196e68f37e5ebeebd056d1fce73af111 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save realgenekim/196e68f37e5ebeebd056d1fce73af111 to your computer and use it in GitHub Desktop.
Download ZIP
Chromium Seam Analysis: A Michael Feathers-Style Claude Code Reading
Raw
chromium-michael-feathers.md

Chromium Seam Analysis: A Feathers-Style Reading

Someone asked me about using Claude Code for huge codebases, including legacy systems in Ada. I had mentioned that the key seems to be able to make these large code bases modular enough so that both LLMs and humans can reason about them.

You had mentioned experiments you had done with LLMs making changes to Chromium, a code base that is similar in size to this particular code base.

I had made the claim that LLMs seem to do an amazing job understanding large code bases, and suspected they could do the equivalent of summoning Michael Feathers (author of "Working Effectively With Legacy Code") — if it could advise on how to split a large system into two smaller systems, it could recursively be able to partition large systems into manageable smaller systems.

Here is the output of a quick experiment. Literally a handful of prompts: "clone the Chromium repo," "summon your inner Michael Feathers and find natural seams where we can further modularize the codebase." Claude Code explored the codebase in parallel — top-level structure, god objects, dependency violations, and existing seam patterns — and synthesized the analysis below in about two minutes.

About the Codebase

  • What it is: Chromium is the open-source project behind Google Chrome, Microsoft Edge, Brave, Opera, and most modern web browsers. It includes the browser shell, the Blink rendering engine, V8 JavaScript engine, networking stack, GPU pipeline, and multi-process sandboxing infrastructure.
  • First commit: September 2, 2008 (original public release)
  • Age: ~18 years of continuous development
  • Total commits: 1,000,000+ (as of 2024 — one of the most actively committed repos in existence)
  • C/C++ lines of code: ~30.8 million (136,748 .cc/.h/.cpp/.c/.mm files)
  • Total source files (all languages): ~192,000 files; ~490,000 files total on disk
  • Disk size: 6.6 GB (shallow clone, no history)
  • Languages: C++, Python, JavaScript, Java (Android), Objective-C++ (macOS/iOS), Mojo IDL, GN build files
  • Build system: GN (generates Ninja build files)
  • Snapshot used: commit cd87da23b77a (2026-03-31)

How to Download (Latest Only, No History)

# Blobless shallow clone — fastest method (~minutes, not hours)
# Downloads tree structure immediately; fetches file contents on demand
git clone --depth 1 --filter=blob:none --no-checkout \
  https://github.com/chromium/chromium.git chromium
cd chromium
git checkout   # this downloads actual file contents (~6.6 GB)
  • A full clone with history is 50+ GB and can take hours — avoid unless you need git log/git blame
  • The official method uses Google's depot_tools and fetch chromium, but the above works for code exploration
  • After deep exploration of the codebase, Chromium already has some excellent seam architecture — and some places where it's crying out for more.

The Good: Seams That Already Work

  • 1. The content/public/ Embedder API — This is the crown jewel. A clean 3,393-line interface (ContentBrowserClient) that separates the rendering engine from the browser shell. Chrome, Android WebView, and Headless mode all plug in through this seam. Pure Feathers: you can alter behavior (swap the entire browser UI) without editing content/.

  • 2. KeyedService DI Framework — 1,027 service factories across the codebase. Lazy initialization, lifecycle management, incognito handling, test mockability. This is the dependency injection backbone. When someone needs a service, they go through a factory keyed to BrowserContext — a textbook object seam.

  • 3. The components/ Layer — 400+ components with 246 individual DEPS files enforcing boundaries. Autofill, bookmarks, sync, password manager — all designed to be reusable across embedders.

The Pain Points: Where Seams Are Needed

  • 4. The God Objects — These are the #1 modularization targets:
File Lines Includes Included By Problem
content/browser/renderer_host/render_frame_host_impl.cc 19,956 198 358 files Handles navigation, security, storage, media, payments, autofill, webauthn — everything
content/browser/web_contents/web_contents_impl.cc 12,619 — — Similar sprawl
chrome/browser/chrome_content_browser_client.cc 9,177 — 77 files Integration point for all content/browser interactions
chrome/browser/ui/browser.h 1,398 47 2,603 files The single coordinator for all browser UI

  • Feathers would call these "pinch points" — places where every change radiates outward. RenderFrameHostImpl is the poster child: it's where navigation, security, storage, media, payments, and autofill all converge. The natural seam is to extract delegates: NavigationDelegate, SecurityDelegate, StorageDelegate, MediaDelegate.

  • 5. about_flags.cc — 13,378 Lines of Feature Registration

    • Every feature in Chrome must modify this central file plus flag_descriptions.h (8,400 lines). This is the opposite of a seam — it's a convergence point that forces coupling. The natural seam: a distributed feature registry where each feature self-registers, eliminating the central file entirely.

  • 6. The Circular Dependency Problem — crbug.com/353332589

    • chrome/browser/BUILD.gn contains 31 separate allow_circular_includes_from blocks — each one an explicit admission that the intended modularity has broken down. The blocking headers appear repeatedly:
    • profile_policy_connector.h
    • management_service_factory.h
    • profile_manager.h
    • system_network_context_manager.h
    • protocol_handler_registry_factory.h
    • These are the load-bearing walls preventing chrome/browser/ from decomposing into independent modules. Componentizing these headers (moving them to components/) would unlock the entire modularization chain.

  • 7. Profile: The Billion-Dollar Coupling

    • Profile extends content::BrowserContext and mixes three concerns: user configuration + browser context + service factory host. The code itself acknowledges this — there's a comment in profile.h: "Instead of adding more members to Profile, consider creating a KeyedService." The seam: extract a ProfileServiceHost interface.

  • 8. 3,451 Preprocessor Seams in chrome/browser/ Alone

    • #if BUILDFLAG(IS_ANDROID), #if BUILDFLAG(IS_WIN) || BUILDFLAG(IS_MAC) || BUILDFLAG(IS_LINUX), #if BUILDFLAG(IS_CHROMEOS)
    • Each #if BUILDFLAG is a preprocessing seam — it works, but it's the weakest kind. You can't test alternate paths without recompiling. The stronger seam: platform strategy interfaces where platform-specific behavior is injected at runtime via the existing KeyedService/delegate patterns.

The Feathers Playbook: Where to Cut

  • If I were prioritizing, these are the natural seams in order of impact:

  1. RenderFrameHostImpl decomposition — Extract 4-5 delegate interfaces from this 20K-line monster. The methods already cluster by concern. This is the single highest-leverage refactoring in the codebase.

  2. Componentize the Profile-blocking headers — The 6-8 headers that appear in allow_circular_includes_from are the dam. Move them to components/ and the circular deps collapse.

  3. Distributed feature registration — Replace about_flags.cc convergence with self-registering features. Each feature defines its own flag in its own directory.

  4. Browser.h interface extraction — 2,603 dependents means any change here rebuilds half of chrome/. Extract TabController, WindowController, CommandController interfaces.

  5. Replace #if BUILDFLAG with platform delegates — Convert compile-time branching to runtime injection where testability matters.

  • The meta-pattern: Chromium's intended architecture (content/public, components, KeyedService) is sound. The debt lives in the places where the architecture wasn't enforced — god objects that grew incrementally, central files that every feature touches, and circular deps that were allowed "temporarily" and calcified. The seams are already visible in the dependency graph; they just need to be cut.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment