mouadja02 README Writer
A great README answers four questions in order: what is this, why should I care, how do I run it, how do I use it. Everything else is optional — include it only if a new contributor would be blocked without it.
Before Writing
Read these first — don't guess:
package.json/pyproject.toml/requirements.txt— project name, dependencies, scriptsdocker-compose.yml— services, ports, env varsAGENTS.md/CLAUDE.md— existing docs to not duplicate- Main entry point (e.g.,
main.py,src/index.ts) — what it actually does .env.example— what config is needed
Structure by Project Type
Python Tool / CLI
# project-name
One sentence: what it does and why you'd use it.
## Features
- Bullet of main capability 1
- Bullet of main capability 2
## Requirements
- Python 3.11+
- `pip install -r requirements.txt`
## Setup
```bash
cp .env.example .env
# Edit .env: set API_KEY=...
pip install -r requirements.txt
Usage
python main.py --input mapping.json --output ./dbt_project/
Configuration
| Variable | Default | Description |
|---|---|---|
API_KEY |
— | Required. Your LLM API key |
MODEL |
claude-sonnet-4-6 |
LLM model to use |
Project Structure
src/
├── parser.py # Reads input files
├── generator.py # Generates output
└── main.py # Entry point
---
### FastAPI Backend
```markdown
# project-name
One sentence.
## Stack
- Python 3.12 + FastAPI
- [LiteLLM / Anthropic SDK]
- Docker
## Quick Start
```bash
cp .env.example .env
docker compose up --build
API available at http://localhost:8000 · Docs at http://localhost:8000/docs
API Reference
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v1/generate |
Submit a mapping for generation |
GET |
/api/v1/jobs/{id} |
Check job status |
GET |
/health |
Health check |
Environment Variables
| Variable | Required | Description |
|---|---|---|
ANTHROPIC_API_KEY |
Yes | Anthropic API key |
DATABASE_URL |
No | SQLite path (default: ./db.sqlite) |
Development
pip install -r requirements.txt
uvicorn main:app --reload
Run tests: pytest
---
### React / Vite Frontend
```markdown
# project-name
One sentence.
## Tech
Vite + React 18 + TypeScript + Tailwind CSS
## Start
```bash
pnpm install
pnpm dev # http://localhost:5173
Build
pnpm build
pnpm preview
Environment
Copy .env.example to .env:
VITE_API_URL=http://localhost:3000
---
### Monorepo (pnpm workspaces)
```markdown
# project-name
One sentence about the overall system.
## Architecture
apps/ ├── web/ # React frontend (port 5173) ├── api/ # Fastify API (port 3000) └── renderer/ # Worker packages/ ├── shared/ # Shared TypeScript types └── prompt/ # AI prompt builder
## Quick Start
```bash
pnpm install
pnpm dev # starts all services
Or with Docker:
docker compose up --build # http://localhost:8080
Services
| Service | Port | Description |
|---|---|---|
| web | 5173 | React UI |
| api | 3000 | REST + WebSocket API |
| nginx | 8080 | Reverse proxy |
Development
Each app has its own pnpm dev — run from root to start all, or cd apps/web && pnpm dev for just one.
Environment
Copy .env.example → .env. Required:
ANTHROPIC_API_KEY— for AI generation
---
### dbt Project
```markdown
# project-name
dbt project for [company/domain] on Snowflake.
## Data Sources
| Source | Schema | Description |
|--------|--------|-------------|
| `salesforce` | `RAW_DB.SALESFORCE` | CRM data |
| `oms` | `RAW_DB.OMS` | Order management |
## Models
models/ ├── staging/ # 1:1 source casts ├── intermediate/# Business logic joins └── marts/ ├── core/ # Shared dimensions and facts └── finance/ # Finance-specific models
## Setup
```bash
pip install dbt-snowflake
cp profiles.yml.example ~/.dbt/profiles.yml
dbt deps
dbt debug
Run
dbt run # all models
dbt run --select tag:daily # daily models only
dbt test # run all tests
dbt docs generate && dbt docs serve
---
### AI Agent / Tool
```markdown
# project-name
One sentence: what the agent does, what it takes as input, what it produces.
## How it works
1. **Parse** — reads [input format]
2. **Plan** — [what the agent decides]
3. **Generate** — produces [output format]
4. **Validate** — [how output is checked]
## Usage
```bash
python agent.py --input path/to/mapping.json --output ./output/
Input Format
[describe expected input structure]
Output
[describe what is produced and where]
Configuration
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
Required |
MODEL |
Default: claude-sonnet-4-6 |
---
## Writing Rules
**Lead with the value, not the name.** The first sentence should tell a stranger what problem this solves. Not "This is a tool for..." — just what it does.
**Assume nothing is installed.** A new person should be able to copy-paste from Quick Start and have something running. Every command must work.
**Use real examples.** Show actual command output, actual file names, actual API responses — not `<your-value-here>` placeholders in the usage section.
**Keep it honest.** If something is broken, in progress, or requires manual steps, say so. A README that lies is worse than no README.
**Don't over-document.** Omit sections that don't apply. A 50-line README that covers what matters beats a 500-line one that includes auto-generated API docs for internal helpers.
**Badges are optional.** Add CI/CD status badge if CI exists. Skip the vanity badges.
---
## Markdown Formatting Conventions
```markdown
# Project Name ← H1: project name only, once
## Section ← H2: major sections
### Subsection ← H3: variants within a section
`inline code` ← for file names, env vars, values
```code block``` ← for any command or code snippet — always specify language
**bold** ← for emphasis on important terms
> Note: ... ← for callouts / warnings
| Col | Col | ← tables for config vars, endpoints, services
Tone
Write for someone who has never seen this project. Be direct and practical. Skip filler phrases ("This powerful tool..."). Every sentence should convey information a reader needs.