To understand a legacy codebase without documentation, start with one business behaviour. Find the code that implements it, trace its dependencies, check the relevant data and configuration, and record what the evidence supports. Expand the investigation from that verified starting point.
This workflow is for teams inheriting an unfamiliar application, engineering leaders planning a change, and consultancies taking over a client system. The useful first deliverable is a small, traceable explanation of how one part of the system works.
SocratiCode gives an AI coding assistant tools to search indexed code and inspect its relationships. The assistant remains the interface. Engineers validate the findings and decide which changes are safe to make.
1. Define the behaviour and the source boundary
Choose a question someone needs answered: where an order is cancelled, how permissions are checked, or what happens when a background job retries. A question about observable behaviour gives the investigation a clear starting point and a way to check the answer.
For illustration, suppose a team inherits an order service and needs to understand whether cancelling an order also releases reserved stock. That is a more useful first question than asking for an explanation of the entire repository.
Before searching, identify:
- the repository and source revision being investigated, including any local changes;
- the application entry point, job, screen, or API associated with the behaviour;
- other repositories or services that may take part;
- the people authorised to inspect the source and the environment in which it will be indexed.
SocratiCode indexes supported files from the checkout it is given. Confirm that indexing has completed with codebase_status. Check file types, ignore rules, and freshness before treating the results as coverage of the relevant code. Search support and graph support differ by language; the language support documentation explains those differences.
For sensitive source, review where code, embeddings, and assistant inputs travel before choosing a setup.
2. Find code by behaviour, then use its exact names
Start with a question that describes the behaviour in ordinary language. SocratiCode combines semantic search with keyword search, so the assistant can look for relevant implementations even when the investigator does not yet know their names.
For the order example, ask the assistant:
Use SocratiCode to find where cancelling an order changes its status and releases reserved stock. Show the relevant file paths and line ranges, then read the source before explaining the behaviour.
Search results are starting points. Open the source around each result, identify the actual functions, data fields, and error paths, and use those exact identifiers to narrow the next search. A result that mentions cancellation might be a test, a client wrapper, or an unused implementation.
The search tool is codebase_search. These tool names refer to MCP tools called through a compatible assistant, not commands to paste into a terminal. The setup guides explain how to connect an existing coding host.
If a search finds nothing, check the query and index coverage before concluding the behaviour is absent. Try a known route, error message, table name, or identifier when one is available.
3. Trace dependencies and callers
Once a likely implementation is found, inspect the relationships around it:
codebase_graph_queryshows the file's recorded imports and dependents.codebase_symbolshows a symbol's definition, callers, and callees.codebase_flowfollows recorded calls forward from a chosen entry point.
In the order example, inspect the cancellation handler, the stock update it reaches, and the callers that can trigger cancellation. Read the source to check the order of operations, transaction boundaries, and error handling. Follow any job, API, or event hand-off to its actual contract.
These graphs come from static analysis of indexed source. Dynamic dispatch, reflection, dependency injection, generated code, and runtime configuration can leave relationships unresolved. A missing edge or a result showing no callers does not establish that code is unused. The impact-analysis documentation describes the accepted limits.
If the workflow crosses repositories, index and link the relevant projects for search. Linked search can return results from several repositories, but it does not create dependency or call-graph edges between them. Trace each repository separately and verify the hand-off through its API, event schema, configuration, or tests. See the cross-repository guide for the setup and boundaries.
4. Add the documentation that still exists
An undocumented application may still have a database schema, API specification, infrastructure configuration, test suite, or deployment runbook. Those sources can explain details that are difficult to infer from application code alone.
SocratiCode can index selected text files and directories as context artifacts. Configure the material the team is authorised to use, inspect the configured artifacts with codebase_context, and search them with codebase_context_search. The context artifact documentation provides the configuration format and exclusion rules.
For the example, compare the cancellation code with the order-status schema and any documented stock-reservation contract. Check whether the documents describe the same revision and deployment as the source. If they disagree, preserve that disagreement as an unresolved fact until it can be checked.
Context search retrieves material that was supplied. It cannot reconstruct a missing business decision or establish why an undocumented rule was introduced. That may require a maintainer, version history, or a controlled observation of the running system.
5. Check the impact of a proposed change
Understanding the current behaviour becomes useful when the team can assess a concrete change. For example: what needs checking if the cancellation handler stops releasing stock directly and delegates that work to a job?
Use codebase_impact on the relevant file or symbol to identify relationships that may be affected. Combine that list with the callers, configuration, tests, and external contracts already inspected. In the example, checks could include a repeated cancellation request, a failed stock update, and a retry after partial completion, if those scenarios are supported by the actual system.
The impact result is a list of candidates for investigation within the graph's coverage and query depth. It does not prove that the proposed change preserves behaviour. Review the affected source and run the relevant tests and authorised integration checks through the application's real execution path.
For an initial assessment, this step can end with a validation plan. There is no need to change production code just to demonstrate that the team understands which questions must be answered.
6. Preserve a useful handover
Write a short investigation note that another engineer can verify. Include:
- The question: the business behaviour or proposed change being investigated.
- The scope: repositories, source revisions, index status, and known coverage limits.
- The path: relevant entry points, functions, data stores, and service hand-offs, with source references.
- The evidence: source, specifications, configuration, and tests that support each conclusion.
- The unknowns: missing rules, conflicting documentation, dynamic relationships, and checks still needed.
- The next step: the owner and validation needed before a change proceeds.
The team or its assistant authors this note; indexing alone does not produce a verified handover. Review it before adding it to the project's documentation. A maintained note can then be included as a context artifact for later investigations.
For engineering leaders and delivery partners, a useful acceptance check is whether another engineer can follow the references, explain the chosen behaviour, and distinguish confirmed facts from open questions. Measure an evaluation against real tasks and their verification effort before making claims about time saved.
Start with one investigation
Connect SocratiCode through the guide for your coding host, complete the index, and choose one behaviour that matters to the team. The workflow uses the open-source engine. Teams that need a shared baseline can then review the shared-context operating pattern.
For consultancies and implementation teams planning to use SocratiCode in client work, the site's design-partner route is the place to discuss delivery, support, and the service model. SocratiCode Cloud remains a private beta, with deployment and service requirements confirmed for each engagement.