Dotfiles

Dotfiles Guidelines

• All comments and documentation must be written in English
• Keep configurations simple and minimal — avoid over-engineering
• Avoid unnecessary comments — prefer self-documenting code. Only add comments when they explain why something is done, not what it does. Configuration option names are usually self-explanatory.
• Primary platform: macOS (Darwin), but keep configs portable to Linux (EC2, servers)
• Avoid macOS-specific features when a cross-platform alternative exists
• Use uname or similar checks when platform-specific code is unavoidable

Installation & Package Management

CRITICAL: Always use the Makefile for installing tools and applications. Never install packages directly with brew install, npm install -g, or other package managers. See makefile.md for details.

Symlink Conventions

Configuration files are symlinked from this repo:

• ~/.config/fish → ~/.dotfiles/fish
• ~/.config/nvim → ~/.dotfiles/nvim
• ~/.config/Cursor/User/* → ~/.dotfiles/cursor/*

Always update the Makefile when adding new symlinked configurations.

Code Style

Comments

• Minimal comments: Only comment when explaining non-obvious behavior or important context
• No obvious comments: Don't comment what the code already clearly shows (e.g., scrollback_lines = 200000 doesn't need a comment)
• Self-documenting: Prefer clear variable/option names over comments
• When to comment: Only when explaining why something is configured a certain way, not what it does

Primary Work Context

Main technologies used daily:

• TypeScript — Use strict mode, prefer explicit types
• PostgreSQL — Use UPPER CASE for SQL keywords
• Node.js — Managed via Volta