📖 README.ai

Structured context for AI-powered development

🤔 The Problem

AI coding assistants are incredible, but they have a fundamental limitation: they don't know your project. When an AI looks at your codebase, it sees:

import { useState } from 'react'
import axios from 'axios'

But it doesn't know:

• Which React version you're using and its specific quirks
• How you actually use axios across your project
• Your team's established patterns and conventions
• Which parts of a library are safe to use vs. deprecated

The result? Hallucinated APIs, outdated suggestions, and wasted tokens as AI tools try to reverse-engineer your project's intent from thousands of lines of code.

💡 The Solution

README.ai is a machine-readable manifest that lives alongside your code. It provides AI tools with structured, curated context about:

• 📦 Dependencies - Not just versions, but how you use them
• 🏗️ Architecture - High-level structure and patterns
• 🔧 Code Conventions - Your team's established practices
• 🔄 Cross-project References - How microservices and libraries relate

✨ Why README.ai?

For Developers

# One command to set it up
npx readme-ai init

# Automatic updates with every commit
git commit -m "Add new API endpoint"
# README.ai updates itself! ✨

For AI Tools

When an AI encounters your project:

1. It detects README.ai automatically
2. Parses the structured context
3. Understands your project in seconds, not minutes
4. Gives you better, more accurate assistance

The Result

- AI: "I see you're using axios. Here's how to make a GET request..."
+ AI: "I see you're using axios 1.6.0 with your custom interceptor pattern from apiClient.js. Here's how to add that new endpoint following your established error handling..."

🎯 Vision

README.ai aims to become the universal standard for AI-context in software projects. We're building:

• 🔄 Auto-generation tools that keep context in sync with code
• 🔌 Universal discovery so any AI tool can find and use README.ai
• 📚 Ecosystem of schemas for popular libraries and frameworks
• 🤝 Integration with existing AI coding assistants

🚀 Current Status

We're in the very early stages! This is a placeholder repository while we scope out the project. We're exploring:

• The optimal schema format (JSON? YAML? TOML?)
• Git hooks for automatic updates
• Integration with popular AI tools (Continue, Cursor, etc.)
• Community-driven library profiles

🛣️ Roadmap

• Phase 0: Discovery - Define the schema and tooling approach
• Phase 1: Foundation - Basic auto-generation from diffs
• Phase 2: Integration - Partner with AI tool developers
• Phase 3: Ecosystem - Community library profiles and standards

🤝 Get Involved

We're looking for:

• Early adopters to try prototypes and provide feedback
• AI tool developers interested in integration
• Schema designers to help define the format
• Library maintainers to create official README.ai profiles

Ways to contribute

• ⭐ Star this repo to show interest
• 🗣️ Join the discussion in Issues
• 💡 Share your ideas for what README.ai should include
• 🔧 Help us build the tooling

📄 License

MIT © README.ai Contributors