From c9e4337e15033ce58140f6c94747b023ed4221e0 Mon Sep 17 00:00:00 2001 From: Jarvis Prime Date: Thu, 5 Mar 2026 04:24:26 +0000 Subject: [PATCH] feat: upgrade repo-level doc prompt for CLAUDE.md-quality narratives Repo summaries now generate structured, opinionated overviews with: - What This Project Does (purpose, not generic description) - Architecture (entry points, request flow, key abstractions) - Key Patterns (conventions an agent must match) - Where Things Live (non-obvious file ownership map) - Gotchas (surprises, race conditions, naming traps) Addresses Mike/Dmitry feedback: roll-up summaries must be 'actually usable.' Old prompt produced 4-6 generic sentences. New prompt produces a real onboarding doc that reads like a senior engineer wrote it. --- docgen.py | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/docgen.py b/docgen.py index be710a9..4f8922b 100644 --- a/docgen.py +++ b/docgen.py @@ -90,17 +90,33 @@ def generate_repo_doc(readme: str, entry_files: list[tuple[str, str]]) -> str: readme_section = readme[:3000] if len(readme) > 3000 else readme - prompt = f"""You are a senior software engineer writing a project overview. + prompt = f"""You are a senior software engineer writing a project overview that will be consumed by AI coding agents and new developers joining the team. -Based on the README and key source files below, write a 4-6 sentence summary of this project. Cover: -- What the project does (its purpose) -- Key architectural patterns (routing, middleware, etc.) -- The main abstractions and how they fit together +Write a concise but opinionated overview of this project. This should read like the best possible onboarding document — the kind a senior engineer writes after spending a week with the codebase. It should help someone (human or AI) understand the system well enough to start making changes confidently. + +Structure your response with these sections (use markdown headers): + +## What This Project Does +One paragraph. What problem does it solve? Who uses it? Be specific, not generic. + +## Architecture +How is the code organized? What are the key abstractions and how do they compose? Mention the main entry points and the flow of a typical request/operation through the system. Name specific files and types. + +## Key Patterns +What conventions does this codebase follow? Middleware chains, handler signatures, error handling patterns, configuration approach. An agent needs to match these patterns when writing new code. + +## Where Things Live +A brief map: which directories/files own which concerns. Focus on the non-obvious — things a newcomer would waste time searching for. + +## Gotchas +Anything surprising, non-obvious, or easy to get wrong. Race conditions, initialization order, naming conventions that break expectations. + +Be direct and opinionated. Say "the router is the heart of the system" not "the project contains routing functionality." Use file names and type names. Skip generic statements about Go or web frameworks. README: {readme_section} -Key source files: +Key source files (with their generated documentation): {files_section} Project Overview:"""