How to Establish Intent the First Time You Open a Repository with Claude Code

How to Establish Intent the First Time You Open a Repository with Claude Code

Morning coffee. A new client. A new repository. And one very common question:

“Where do we even begin?”

If you are a consultant or engineer walking into an unfamiliar codebase, the first challenge is rarely writing code. The challenge is understanding what the system is supposed to do.

In the past, that meant digging through outdated documentation, tribal knowledge, and thousands of lines of code.

Today, tools like Claude Code change the workflow. Instead of trying to reverse-engineer everything manually, engineers can establish intent — a clear statement of what the system is meant to be — and let AI reason over the repository alongside that intent.

Intent becomes the architectural north star for the system.

So the real question becomes:

How do you establish intent when you first arrive at a repository?

What Is Intent?

Intent is a structured description of what the system is supposed to do and how it should behave.

Instead of relying on scattered documentation, intent lives inside the repository.

A typical structure might look like this:

repo/

  intents/

    system.md

    api.md

    ui.md

  src/

  tests/

These files describe things like:

• System architecture

• API contracts

• Technology choices

• Constraints and design principles

The key shift is this:

Old development model:

Code → Documentation

Intent-driven model:

Intent → AI reasoning → Code

Why Establishing Intent Matters

When a repository has no intent defined, AI tools are limited to reasoning about what exists.

When intent is present, AI can reason about:

• what exists

• what should exist

• what should change

That transforms the development process.

Instead of asking:

“What does this code do?”

You can ask:

“Does the system match the intent?”

Scenario 1: Starting With a Legacy Repository

Legacy systems are the most common scenario consultants encounter.

There may be:

• incomplete documentation

• outdated architecture diagrams

• multiple frameworks

• years of accumulated code

The first goal is not rewriting the system.

The first goal is discovering its intent.

Step 1: Ask Claude to Analyze the Repository

Example prompt:

Analyze this repository and summarize:

- architecture

- frameworks

- key components

- service boundaries

Claude can quickly detect patterns such as:

• Spring Boot services

• React frontends

• REST APIs

• database access layers

This gives you an initial architectural map.

Step 2: Create the First Intent File

Now you establish the first intent overlay.

Example:

intents/system.md

System Intent

This repository contains a customer order management system.

Architecture:

- Spring Boot REST API

- React frontend

- PostgreSQL database

Goals:

- Maintain stable API contracts

- Ensure separation between service and persistence layers

- Prepare system for future microservice extraction

This does not need to be perfect.

It simply establishes direction.

Step 3: Reconcile Code With Intent

Now you can ask Claude questions like:

Compare the repository to the defined intent.

Highlight architectural inconsistencies.

This is where AI becomes a system analyst.

Legacy Secret

When working with legacy systems:

Start with high-level intent first.

Do not try to document every service immediately.

Instead define:

• system purpose

• architecture style

• constraints

Then refine over time.

Scenario 2: Greenfield Development

Greenfield projects are where intent-driven development shines the most.

Because here, intent becomes the blueprint for the entire system.

Instead of writing code first, you define the system architecture in intent files.

Example:

intents/system.md

System Intent

Purpose:

A dice rolling demo application.

Architecture:

- React frontend

- Node.js TypeScript REST API

Requirements:

- UI displays dice roll

- API generates random roll

- UI calls API endpoint

Now you can ask Claude:

Generate the initial implementation of this system.

And the system emerges from the defined intent.

Greenfield Secret

Spend more time on intent than code.

A well-written intent file can generate an entire system skeleton.

That dramatically accelerates development.

Scenario 3: Modernization or Upgrade Projects

Many consulting engagements involve incremental modernization.

In these cases, intent helps guide the evolution of the system.

Example intent file:

Modernization Intent

Goal:

Gradually migrate monolithic architecture toward microservices.

Constraints:

- Existing API contracts must remain stable

- Database schema cannot change immediately

Migration Plan:

1. Extract customer service

2. Introduce API gateway

3. Separate UI deployment

Now Claude can help plan and execute the modernization steps.

Modernization Secret

Intent allows modernization to happen incrementally.

Instead of rewriting everything, the architecture evolves toward the defined goals.

How Consultants Should Approach a New Repository

When walking into an unfamiliar project, follow this sequence.

Step 1

Ask Claude to analyze the repository.

Step 2

Write the first system intent file.

Step 3

Ask Claude to reconcile code and intent.

Step 4

Gradually expand intent coverage:

• API intent

• UI intent

• architecture intent

Step 5

Use intent as the ongoing development guide.

The Real Shift

Intent-driven development changes the way engineers approach unfamiliar systems.

Instead of asking:

“Where do I start in this codebase?”

The new question becomes:

“What is the intent of this system?”

Once that is clear, tools like Claude Code can reason over the system and help guide its evolution.

Intent becomes the living architecture of the repository.

And for consultants stepping into unknown environments, that is an incredibly powerful starting point.

Key Takeaways

• Intent files define the architecture and goals of a system.

• Legacy systems benefit from an intent overlay approach.

• Greenfield projects should start with intent before writing code.

• Modernization projects use intent to guide incremental evolution.

• AI tools like Claude Code can reason over code and intent together.

The result is a new development model where systems evolve from declared intent rather than ad-hoc code changes.

And for engineers facing unfamiliar repositories every day, that may be one of the most important shifts in modern software development.