codebase_summarizer/spec/main.md

codebase_summarizer is a command-line tool written in Rust that recursively traverses a given directory or the current working directory if none is given. It identifies code files and extracts a concise one-file summary of the codebase enriched with DOC-strings/comments.

The outputs of this tool are:

• codebase_summary.md, a markdown file like this example

  # Codebase Architecture Map
  
  ## File: pkg/auth/service.go
  ### func (s *AuthService) Login(user, pass string) (*Token, error)
  **Doc:** 
  // Login validates the user credentials against the database.
  // Returns a JWT token if successful or an error if unauthorized.
  
  ## File: cmd/api/main.go
  ### type Config struct
  **Doc:** 
  // Config holds the application environment settings.
  

• agents.md, a read me type file for agents if no such file exists yet. This file instructs the coding agents how to use the codebase_summary

  # Codebase Navigation Protocol
  
  You have access to codebase_summary.md. This file contains a compressed map of the codebase, including exported signatures and their associated documentation comments.
  
  Protocol:
  
  Consult Summary First: Use the doc-strings in codebase_summary.md to understand the intent and usage of functions without reading the full implementation.
  Identify Targets: Identify the specific files containing the logic you need.
  Deep Dive: Open the identified files to study the internal logic/edge cases before proposing a solution.
  After making changes: run the codebase_summarizer tool to update the codebase_summary.md again if necessary