AIにソースコードを読ませる前に「地図」を渡すためのツール群を作ってみた Passing raw source code directly to AI assistants like ChatGPT or GitHub Copilot often lea…

As AI coding assistants become routine tools for legacy system investigation, a practical friction point has emerged: handing an AI a pile of raw source files often produces generic, poorly targeted responses. The model simply lacks the navigational context it needs to reason effectively about an unfamiliar codebase. One developer addressed this by building a small suite of preprocessing tools designed to generate a structural 'map' of a project before any code is shown to the AI.

The problem is intuitive once you encounter it firsthand. ChatGPT and GitHub Copilot excel at conversational reasoning and code completion, but when asked to analyze a large, undocumented system from scratch, they frequently miss the forest for the trees. Without knowing which classes are central, where the entry points are, or how modules depend on each other, the AI defaults to surface-level observations that force developers into repeated rounds of clarifying prompts.

The toolset described in the article targets C# projects and generates structured overviews—namespace trees, class hierarchies, method call graphs, and inter-project dependency summaries—formatted as readable text or diagrams. These artifacts are then bundled with relevant source files and submitted to the AI together. The goal is to give the model an architectural scaffold it can use to orient itself before diving into implementation details, much like how a good technical document leads with a high-level diagram.

This approach resonates with longstanding practices in software documentation. Presenting a UML class diagram or a module dependency graph before asking questions has always helped human reviewers get up to speed faster, and the same intuition appears to hold for LLMs. Interestingly, major AI coding platforms are beginning to formalize this idea at the product level. GitHub Copilot now supports repository-scoped custom instructions via `.github/copilot-instructions.md`, and tools like Cursor allow teams to define rule files that prime the model with domain context before any conversation starts. The handmade toolset described in this article is, in effect, a manual predecessor to those built-in mechanisms.

It is also worth examining the context-window argument. GPT-4o supports up to 128K tokens, and Gemini 1.5 Pro has crossed the one-million-token threshold, which might suggest that simply dumping more code is becoming viable. Practitioner experience and some emerging research suggest otherwise: longer contexts can dilute the model's effective attention, causing important details to get lost amid less relevant material. A tight, well-structured preamble that directs the AI's focus may outperform raw volume, particularly for complex, multi-layered systems.

Projects born from real-world friction tend to produce the most transferable insights for a developer community. The tools described here are likely to resonate especially with engineers working in enterprise environments where C# legacy codebases are common and AI assistance is increasingly expected but imperfectly integrated. Whether or not this specific implementation sees wider adoption, the underlying principle—prepare the AI's context deliberately rather than leaving it to fend for itself—seems destined to remain a best practice as these tools continue to mature.