Skip to main content
Skip to content
Menu

Development teams Intermediate 3 parts

Build a Python script that auto-generates architecture decision records from your codebase

You'll have a working script that analyzes your code structure and generates ADR drafts for your team to review and finalize, saving hours of documentation overhead.

What you'll make

ADR Generator Script

  1. scan_codebase() — file structure and dependency analysis: what to include
  2. extract_patterns() — AI identification of architectural choices: what to include
  3. generate_adr_draft() — structured ADR template population: what to include
  4. main() — orchestration with human review checkpoints: what to include

Paste your complete Python script with example output from running it on your actual codebase

The 3 parts

Each part ends with a check you can see.

  1. Map Hidden Decisions

    Scan your codebase by hand to identify 5-7 architectural choices that aren't documented anywhere but are visible in the code structure

    Done when

    A list of 5-7 specific architectural decisions with the file/folder evidence that shows each choice was made

  2. Build the Pattern Scanner

    Create the scan_codebase() and extract_patterns() functions that use AI to identify architectural patterns in your code structure

    Done when

    Working functions that can scan your codebase and identify at least 3 of your hand-mapped decisions from Task 1

  3. Draft ADR Templates

    Build generate_adr_draft() and main() functions that convert detected patterns into structured ADR drafts with human review checkpoints

    Done when

    A complete script that generates ADR drafts for detected patterns and includes explicit prompts for human review and editing

    Capstone: you put together your ADR Generator Script.

Where this helps

An elective: a single lesson that sits outside rtwo's job certificates and doesn't count toward one.

About this lesson

What you'll be able to do

  • Run a working Python script that scans your real codebase and generates ADR drafts with architectural decisions extracted from code patterns
  • Identify the 3-5 types of architectural choices where AI gets it right vs where human context is required
  • Have a documented workflow for keeping ADRs current as your codebase evolves
  • Know when to trust AI's architectural analysis vs when to override with team knowledge

Who it's for

  • Development teams drowning in undocumented architectural decisions
  • Tech leads who want to automate ADR creation but need human oversight on the output
  • Anyone maintaining a Python codebase who can read and modify scripts

What it won't cover

  • Writing ADRs from scratch without existing code to analyze
  • Complex enterprise deployment or CI/CD integration
  • Learning ADR format fundamentals — assumes you know what good ADRs look like
  • Multi-language codebases beyond Python

Skills you'll practise

  • Code structure analysis with AI
  • Architectural pattern recognition
  • Human-AI judgment calibration
  • Documentation automation workflow design