# Onboarding a legacy repository

> An unfamiliar service with no tests and no documentation stops being a black box — from “how does this even work” to the first safe change.

Use case

# Onboarding a legacy repository

You have inherited an unfamiliar service — say, notes-api: no tests, no documentation, a muddled commit history. Touching it is risky, yet it has to be developed further. Where do you start, and how do you avoid breaking what works?

[Connect a repository](https://buff.systems/app) [All use cases](https://buff.systems/en/use-cases)

Situation

## An unfamiliar service with no tests and no documentation stops being a black box — from “how does this even work” to the first safe change.

What gets in the way

- It is unclear how the project is built — where things live, which domains and links there are.
- You need to understand the logic of one specific place — for example, how the /search response is built.
- You need verified answers about how it works, to attach to a task.
- It is unclear where the risk areas and technical debt are — what to tackle first.
- No tests and no documentation — changing anything blind is dangerous.
- No working environment — the code cannot be built or run against tests.

Solution 01

## Audit — the project as it is

An end-to-end review of the codebase: domains, architecture, dependencies, behaviour, risk areas and technical debt — with priorities and clear conclusions. The sections are prepared automatically, even when there are no tests or documentation. The audit shows at once how notes-api is built and what to tackle first.

[About audits](https://buff.systems/en/docs/audits)

**Audit — the project as it is**

← scroll the frame →

Project audit: ready sections on code, architecture and risks.

Solution 02

## “Ask” — a precise answer about the code

When you need to understand one place rather than the whole project, ask a question. Buff reads the source code, as well as connected trackers and documents, and answers with links to files, changing nothing. For example: “Where is the /search response built and how is the query escaped?” — the answer points to notes-api/src/search.ts and explains the logic.

[About “Ask”](https://buff.systems/en/docs/ask)

**“Ask” — a precise answer about the code**

← scroll the frame →

“Ask”: an answer about the code with links to specific files.

Solution 03

## Deep research — a verified document for the task

When you need a worked-out solution rather than a quick answer, two agents (an analyst and a reviewer) prepare a verified document on your code, checking each other’s conclusions. It is easy to attach to a task, so development starts from facts rather than guesses.

[About research](https://buff.systems/en/docs/research)

**Deep research — a verified document for the task**

← scroll the frame →

Deep research: the logic worked through, with options and a recommendation.

Solution 04

## Tools and the first task — no blind changes

Before anything changes, the project gets its development tools — an environment where the code is built, run and checked by tests. Only then does the first task follow the usual cycle: a description in plain words, a specification for your approval — and no blind changes.

[Quick start](https://buff.systems/en/docs/quickstart)

**Tools and the first task — no blind changes**

← scroll the frame →

The first task: description, clarifications and a specification you approve.

Outcome

An unfamiliar legacy codebase stops being a black box: you understand its structure and logic, know the risk areas, and changes go in safely — with tests and under your control.

The first step changes nothing in the code

## Start with a question about your project

Connect a repository and ask the system how your code is built: it reads the source code and answers in minutes, changing nothing. A starting balance is provided to try it out.

[Connect a repository](https://buff.systems/app) [Write to us](mailto:info@buff.systems)

Companies and sole traders can pay by bank transfer and receive closing documents