CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Overview
6 
7`get-rules` is an npm utility that downloads and installs `.mdc` rule files for AI-assisted coding tools (like Cursor) from the johnlindquist/get-rules repository. It's a self-contained Node.js CLI tool that recursively fetches the entire `.cursor/rules` directory structure via the GitHub API, preserving the hierarchical organization of rules.
8 
9## Common Commands
10 
11### Development & Testing
12```bash
13# Install dependencies
14pnpm install
15 
16# Run the CLI locally
17node cli.js
18 
19# Run with custom repo
20node cli.js org/repo
21 
22# Create npm release (automated via GitHub Actions)
23npm run release
24```
25 
26### Package Publishing
27The project uses semantic-release for automated versioning and publishing:
28- Commits to `main` branch trigger the release workflow
29- Conventional commit messages determine version bumps
30- NPM publishing is handled automatically via GitHub Actions
31 
32## Architecture & Key Components
33 
34### Main Components
35 
361. **cli.js**: The core CLI script that:
37   - Accepts optional `org/repo` arguments (defaults to `johnlindquist/get-rules`)
38   - Recursively downloads entire `.cursor/rules` directory structure from GitHub
39   - Downloads only `.mdc` files while preserving directory hierarchy
40   - Moves existing files to temp directory before downloading updates
41 
42### Rule System Architecture
43 
44The downloaded rules follow a specific structure documented in `RULES.md`:
45- Rules are `.mdc` files (Markdown with Components) with YAML frontmatter
46- Organized in hierarchical category directories:
47  - `_/` - Personal rules directory (gitignored)
48  - `_always/` - Global rules that apply to all operations
49  - `_globs/` - Rules organized by file patterns they apply to
50  - Category directories: `cli/`, `docs/`, `git/`, `task/`, `code/`, `react/`, etc.
51- Each rule has `alwaysApply` boolean to control automatic vs manual invocation
52- Frontmatter fields include: `description`, `globs`, `alwaysApply`
53 
54### Key Implementation Details
55 
56- Uses native Node.js `https` module (no external HTTP dependencies)
57- Implements custom `httpsGetJson()` and `downloadFile()` helpers
58- New `downloadDirectory()` function for recursive directory traversal
59- Preserves existing files by moving them to OS temp directory with timestamp
60- Creates nested directory structure automatically
61- User-Agent header included for GitHub API compliance
62- Handles both files and directories from GitHub API responses
63 
64## Customization & Personalization
65 
66The downloaded rules support customization as documented in `PERSONALIZATION.md`:
67- `_/` directory for personal rules (gitignored, not shared with team)
68- Local overrides using `git update-index --assume-unchanged` for team rules
69- `_globs/` directory contains rules organized by file patterns
70 
71## Release Process
72 
73This project uses semantic-release with the following configuration:
74- Analyzes commits to determine version bumps
75- Generates changelog in `CHANGELOG.md`
76- Publishes to npm registry
77- Creates GitHub releases
78- Updates package.json and commits changes
79 
80To trigger a release, push conventional commits to the `main` branch:
81- `feat:` for new features (minor version bump)
82- `fix:` for bug fixes (patch version bump)
83- `BREAKING CHANGE:` for breaking changes (major version bump)