LLM Agent-Friendly Project Setup

A comprehensive guide and toolkit for structuring software projects to maximize effectiveness when working with LLM agents (like GitHub Copilot, Cursor, Claude, etc.).

Purpose

This repository contains best practices, guidelines, and templates developed through iterative work across multiple projects. The goal is to help developers and teams structure their projects in ways that make LLM agents more effective collaborators.

Contents

Core Guides

• LLM Agent Project Setup Guide - Complete guide for setting up new projects with LLM agent collaboration in mind
• LLM Agent Project Migration Guide - Step-by-step guide for migrating existing projects to an LLM agent-friendly structure

Process Guidelines

• Commit Guidelines - Conventional Commits format and best practices
• Ticket Guidelines - Ticket composition and issue tracking best practices
• Branch Management - Git branch strategies for single and multiple agent workflows

Framework Guides

• Framework Selection Guide - Choose the right frontend framework for your project
• Framework Setup Guides - Framework-specific setup guides (SvelteKit, Next.js, React, Vue, etc.)

Example Files

• .cursorrules - Example Cursor IDE rules file that references the process guidelines

Key Principles

1. Clear Context - Well-organized documentation with explicit cross-references
2. Documented Decisions - Rationale and alternatives are explained
3. Consistent Structure - Predictable patterns across the codebase
4. Explicit Dependencies - Clear relationships between components
5. Preserved History - Git history tells a coherent story

Who Is This For?

• Project Maintainers setting up new projects
• Technical Leads migrating legacy systems
• LLM Agent Operators working with AI coding assistants
• Development Teams adopting AI-assisted workflows

Quick Start

For New Projects

1. Choose a framework (if building a web app): Read the Framework Selection Guide
2. Set up your framework: Follow the appropriate Framework Setup Guide
3. Read the LLM Agent Project Setup Guide
4. Copy the .cursorrules example and adapt it to your project
5. Set up your project structure following the recommended patterns
6. Configure your process guidelines in docs/process/

For Existing Projects

1. Read the LLM Agent Project Migration Guide
2. Assess your current project structure
3. Plan an incremental migration strategy
4. Apply the guidelines gradually, ensuring non-breaking changes

Project Types Covered

• Full-Stack Web Applications (SvelteKit, Next.js, etc.)
• Libraries and Packages
• Utilities and Tools
• Monorepos with multiple applications/services
• Legacy System Migrations

Branch Management Strategies

The guides include comprehensive branch management strategies for:

• Single agent workflows
• Multiple parallel agents
• Local-first development
• Remote collaboration
• Hybrid approaches

Contributing

These guidelines were developed iteratively across multiple projects. Contributions, improvements, and real-world examples are welcome!

License

This repository is provided as-is for educational and reference purposes. Feel free to adapt these guidelines to your projects.

Related Resources

• Conventional Commits
• Semantic Versioning
• Git Flow

---

Note: These guidelines are technology-agnostic but include examples from various stacks (SvelteKit, Next.js, PostgreSQL, etc.). Adapt the patterns to your specific technology choices.