ai

How to set up a greenfield agentic project

Eric Thanenthiran·22 February 2026·5 min read

I've been building a lot recently with Claude Code and have found a lot of advice on how to convert an existing code base for AI, but not much on setting up for success on a green field project. I want to be clear that this is my setup because I want to be intentional about the starting point and direction of a project. The best way I've found to get going is to start with an initial, well-defined scaffold and clear roadmap.

For Python projects I use a Cookiecutter project template so that every project looks the same. Now because I have now almost exclusively moved to using Claude, all projects are seeded with a CLAUDE.md file for agents (and a README.md file for humans) for agents. If you want to cut to the chase, you can take a look at my cookiecutter repo here. This is a public repo and it has all the things that I use for a new modern Python project (YMMV).

In the below sections I've generalised these principals for other languages and project types.

Begin with a Clean Project Structure

Before writing prompts or model calls, establish a clear folder structure. In the Python world if you use uv then all of this comes for free out of the box. What you want is a structure that follows modern best practice guidance for you language of choice. It should separate concerns into separate folders and create an easy and logical way to navigate your folder structure.

For most modern projects, there are already established folder structures which can be generated by command line tools:

# python
uv init --package my-app
 
# next.js
npx create-next-app@latest my-app
 
# svelte
npx sv create my-app
 
# vue
npm create vue@latest my-app

A simple starting layout for a Python data project would include the following:

docs/
src/
  app/
    __init__.py
    pipelines/
    orchestration/
    transformation/
    models/
    utils/
  tests/
  config/
  infrastructure/
pyproject.toml
README.md
CLAUDE.md

Now you may spot two items at root level which I create specifically for agents. The CLAUDE.md file and the docs/ folder. Both these are specifically provided for agents to use.

CLAUDE.md

The CLAUDE.md file is sent with every prompt to the LLM, so keep this light to reduce the amount of tokens it consumes.This file is a plain Markdown file placed in a project or folder root that Claude reads automatically at the start of every session to provide persistent context, acting as "project memory" without repeating instructions.

It should ideally under 300 lines and structured with headings, bullets, and specific details to help your coding agent. Focus on durable, frequently needed info across sessions such as:

  • Project overview: Goals, key decisions, structure, patterns, frameworks, libraries, naming conventions.
  • Navigation index: Where to find files/docs.
  • Conventions: Code style, testing/run commands, branch conventions, guardrails, preferences.
  • References: Point to heavier context from other files or resources to avoid bloat.

Here are some tips to hone this file:

  • Use clear headings and bullets, avoid vague instructions.
  • Track in version control for team sharing.
  • Generate drafts by asking Claude to summarise folder docs, then edit for ongoing relevance (cut one-off task details).
  • Prioritise brevity: Include only what applies to most sessions to save context tokens.

docs/

I use the docs folder to simulate memory and to record the status of the project after each session or milestone. Whenever I start working with an agent, I create a roadmap for the project (what Claude does in plan mode). This is saved in a ROADMAP.md file. Ongoing work or smaller tasks can be captured in a TASKS.md file (although recently, I haven't been using this quite as much). I also capture some ideas and general notes in a NOTES.md file for future reference. For example future features or ideas I want to test out. The key again with all these documents is to keep them light and enforce usage by the agent in the parent CLAUDE.md file (which is sent with every prompt).

Use Dependency Management Properly

Adopt modern tooling to manage your dependencies and tightly specify which ones to use. In the Python ecosystem this has largely been solved by uv. In the Javascript world, I'd suggest bun or pnpm. As with all modern software projects:

  • Pin dependencies
  • Use virtual or project-local environments.
  • Avoid global installations.

As AI projects often use a large number of libraries, pinning exact versions will help make your builds reproducible. Another big consideration is safety. By pinning and inspecting all dependencies used by your agent, you can make better choices for project dependencies. This gives you the ability to vet the libraries used and ensure only well supported (and secure packages) are used in your projects. Vibe coding has the inherent risk of introducing any dependency your agent chooses into your project and needless to say, this comes with additional (and unmitigated risks).

Final Thoughts

All in all setting up an Agentic project should follow the same best practice as for any other software engineering project. Added to this are documents that are useful for your agent to be aware of. I use the CLAUDE.md file to provide it information it should always use and the docs/ folder to give it memory - what is the overall roadmap for the project and what is the current state of the project. For Python projects I have a Cookiecutter repo that I use as a starting template. On frontend heavy projects, I fall back to using standard command line tools to create the project structure. There are no hard and fast rules here, but I've found doing this initial setup has helped me keep in control of these projects and allowed me to build production-ready projects that adhere to best practice.

aicode