project-setup-guide

| Type | Examples | Key Sections |

|------|----------|--------------|

| Dotfiles | Shell configs, vim, tmux, git | Tool configs, aliases, keybindings |

| CLI Tools | Scripts, utilities, automation | Installation, usage, options |

| Libraries | npm packages, Python modules | API reference, examples |

| Applications | Web apps, mobile apps, services | Environment setup, deployment |

| Frameworks | Starter kits, boilerplates | Configuration, extending |

| Dev Environments | Docker setups, Nix configs | Prerequisites, bootstrapping |

---

Follow these steps sequentially to create a complete setup guide:

Step 1: Audit the Project

Goal: Understand what exists before documenting.

```

Actions:

1. List all configuration files and their purposes
2. Identify dependencies (package.json, requirements.txt, Brewfile, etc.)
3. Find existing documentation (README, docs/, wiki)
4. Note installation scripts or makefiles
5. Check for environment variables or secrets

```

Questions to answer:

• What does this project do?
• Who is the target audience?
• What are the prerequisites?
• Are there automated setup options?

Step 2: Determine Structure

Goal: Choose sections based on project type.

Universal sections (all projects):

• Title with badges
• One-line description
• Features overview
• Table of Contents
• Installation
• Basic usage

Conditional sections (by type):

| If Project Has... | Include Section |

|-------------------|-----------------|

| Multiple tools/configs | Repository Structure |

| CLI commands | Command Reference |

| Configuration options | Configuration Guide |

| Shell customizations | Aliases & Functions |

| Keyboard shortcuts | Keybindings |

| API surface | API Reference |

| Visual components | Screenshots |

| Breaking changes | Migration Guide |

| Community | Contributing Guide |

Step 3: Document Core Information

Goal: Write the essential sections every README needs.

#### Title Block Pattern

```markdown

# Project Name

> One-line description of what this project does

[](license-url)

[](version-url)

```

#### Features Section Pattern

Use a table for scannable feature lists:

```markdown

| Category | Features |

|----------|----------|

| Shell | Zsh with Powerlevel10k, syntax highlighting, autosuggestions |

| Editor | Neovim with LSP, Telescope, Treesitter |

| Terminal | Tmux with custom keybindings, Alacritty config |

```

#### Repository Structure Pattern

```markdown

\\\`

project-root/

├── config/ # Application configurations

│ ├── app.config.ts

│ └── database.ts

├── src/ # Source code

│ ├── components/

│ └── utils/

├── scripts/ # Automation scripts

│ └── setup.sh

└── README.md

\\\`

```

Step 4: Write Setup Instructions

Goal: Provide clear, tested installation steps.

#### The Dual Setup Pattern

Always offer both automated AND manual options when possible:

```markdown

Quick Start (Recommended)

\\\`bash

# One-line installation

curl -fsSL https://example.com/install.sh | bash

\\\`

Manual Installation

```

#### Prerequisites Pattern

```markdown

| Requirement | Version | Check Command |

|-------------|---------|---------------|

| Node.js | ≥18.0 | node --version |

| npm | ≥9.0 | npm --version |

| Git | ≥2.0 | git --version |

```

#### Environment Variables Pattern

```markdown

| Variable | Required | Default | Description |

|----------|----------|---------|-------------|

| DATABASE_URL | Yes | - | PostgreSQL connection string |

| API_KEY | Yes | - | External service API key |

| DEBUG | No | false | Enable debug logging |

```

Step 5: Document Commands & Usage

Goal: Show users how to actually use the project.

#### Command Reference Pattern

```markdown

| Command | Description |

|---------|-------------|

| npm start | Start development server |

| npm test | Run test suite |

| npm run build | Build for production |

| npm run lint | Check code style |

```

#### Usage Examples Pattern

```markdown

Basic Example

\\\`typescript

import { something } from 'project';

const result = something({

option: 'value'

});

\\\`

Advanced Example

\\\`typescript

// More complex usage with all options

import { something, configure } from 'project';

configure({

debug: true,

timeout: 5000

});

const result = await something({

option: 'value',

callback: (data) => console.log(data)

});

\\\`

```

Step 6: Add Supporting Sections

Goal: Complete the README with helpful extras.

#### Configuration Pattern

```markdown

Configuration file: config.json

\\\`json

{

"setting1": "value",

"setting2": true,

"nested": {

"option": "value"

}

}

\\\`

| Option | Type | Default | Description |

|--------|------|---------|-------------|

| setting1 | string | "default" | Description of setting1 |

| setting2 | boolean | false | Description of setting2 |

```

#### Troubleshooting Pattern

```markdown

```

#### Updating Pattern

```markdown

\\\`bash

# Pull latest changes

git pull origin main

# Update dependencies

npm install

# Run migrations (if applicable)

npm run migrate

\\\`

```

#### Uninstall Pattern

```markdown

\\\`bash

# Remove installed files

npm uninstall -g project-name

# Clean up configuration (optional)

rm -rf ~/.config/project-name

\\\`

```

---

For Dotfiles Projects

Must include:

• Tool-by-tool breakdown with features
• Aliases and abbreviations table
• Custom functions documentation
• Keybindings reference (especially for tmux/vim)
• Backup instructions before installation
• Symlink strategy explanation

Example structure:

```markdown

Zsh

• Theme: Powerlevel10k
• Plugins: syntax-highlighting, autosuggestions, fzf
• Custom aliases: [see below](#shell-aliases)

Neovim

• Plugin manager: lazy.nvim
• LSP servers: typescript, lua, python
• Keybindings: [see below](#vim-keybindings)

| Alias | Expansion | Description |

|-------|-----------|-------------|

| ll | ls -la | Long list with hidden |

| .. | cd .. | Go up one directory |

| g | git | Git shorthand |

Tmux

| Key | Action |

|-----|--------|

| Ctrl-a | Prefix key |

| Prefix + \| | Vertical split |

| Prefix + - | Horizontal split |

```

For Libraries/Packages

Must include:

• Installation via package manager
• Import/require examples
• API reference with types
• Multiple usage examples (basic → advanced)
• TypeScript types documentation (if applicable)

Example structure:

```markdown

\\\`bash

npm install package-name

# or

yarn add package-name

# or

pnpm add package-name

\\\`

\\\`typescript

import { mainFunction } from 'package-name';

const result = mainFunction('input');

\\\`

`mainFunction(input, options?)`

| Parameter | Type | Required | Description |

|-----------|------|----------|-------------|

| input | string | Yes | The input to process |

| options | Options | No | Configuration options |

Returns: Result

Example:

\\\`typescript

const result = mainFunction('hello', { uppercase: true });

// => 'HELLO'

\\\`

```

For Applications

Must include:

• System requirements
• Environment setup (env vars, config files)
• Development vs production instructions
• Database setup (if applicable)
• Deployment guide

Example structure:

```markdown

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Redis (optional, for caching)

Development Setup

1. Clone and install:

\\\`bash

git clone https://github.com/user/app.git

cd app

npm install

\\\`

1. Set up database:

\\\`bash

createdb myapp_dev

npm run db:migrate

npm run db:seed

\\\`

1. Configure environment:

\\\`bash

cp .env.example .env

\\\`

1. Start development server:

\\\`bash

npm run dev

\\\`

Production Deployment

See [Deployment Guide](docs/deployment.md)

```

---

Tables

• Use tables for: features, commands, env vars, options, keybindings
• Always include header row
• Align columns for readability in raw markdown

Code Blocks

• Always specify language for syntax highlighting
• Use bash for shell commands
• Use typescript over javascript when types are shown
• Keep examples concise but complete

Collapsible Sections

Use

• [Features](#features)
• [Installation](#installation)
• [Usage](#usage)
• [Configuration](#configuration)
• [Contributing](#contributing)
• [License](#license)

```

---

For detailed, copy-paste-ready templates for each project type, see:

[references/section-templates.md](references/section-templates.md)

---

Before finalizing any README, verify:

• [ ] Accurate: All commands tested and working
• [ ] Complete: All prerequisites listed
• [ ] Scannable: Uses tables, headers, and formatting
• [ ] Accessible: Both quick start and detailed options
• [ ] Maintainable: Easy to update when project changes
• [ ] Consistent: Formatting uniform throughout

---

User: "Create a setup guide for my dotfiles repo"

Claude's approach:

1. Read the repository structure to understand what's included
2. Identify all configuration files and tools
3. Check for existing install scripts
4. Ask clarifying questions if needed (target OS, experience level)
5. Generate README using dotfiles-specific sections
6. Include tool breakdown, aliases, keybindings tables
7. Provide both automated and manual install options