I saw a post on X where someone asked an AI coding assistant to fix a terminal issue.
Instead, it rewrote their entire .zshrc with two lines.
Years of shell tweaks. Gone.
The takeaway isn’t “don’t use AI.”
The takeaway is: don’t keep your entire shell brain in one fragile file.
This post shows a simple way to make your Zsh setup more resilient: split .zshrc into small modules, then load them safely.
Why a monolithic .zshrc is risky
A typical .zshrc ends up containing everything:
- exports and environment variables
- PATH changes
- functions
- toolchain init (NVM, pyenv, etc.)
- aliases (global + per project)
- keybindings
- prompt/theme
That means a “small fix” can accidentally:
- overwrite unrelated sections
- delete careful customizations
- break your shell in ways that are hard to diagnose
When a single file holds all your shell logic, it becomes a single point of failure.
The fix: modular configs
Instead of one big .zshrc, create a folder of focused config files.
1) Create a config directory
mkdir -p ~/.zsh.d
2) Split your config into modules
Here’s an example module list (based on a real-world setup):
~/.zsh.d/
00-exports.zsh
05-paths.zsh
10-functions.zsh
20-nvm.zsh
30-aliases.zsh
40-aliases-proj1.zsh
41-aliases-proj2.zsh
42-aliases-proj3.zsh
43-aliases-proj4.zsh
90-keys.zsh
99-prompt.zsh
Each file has one job. Small file, small blast radius.
Load the modules from .zshrc
Now your .zshrc becomes a stable loader.
# Path to your oh-my-zsh installation.
export ZSH="$HOME/.oh-my-zsh"
# History
HISTFILE=~/.zsh_history
HISTSIZE=50000
SAVEHIST=50000
setopt APPEND_HISTORY INC_APPEND_HISTORY SHARE_HISTORY
# VS Code: disable globbing errors for unmatched patterns
setopt NO_NOMATCH
# Enable command substitution in prompt
setopt prompt_subst
# Load all modular config files safely
for f in ~/.zsh.d/*.zsh; do
[ -f "$f" ] && source "$f"
done
That’s the core change.
Important detail: load order matters
When you load files via ~/.zsh.d/*.zsh, Zsh loads them alphabetically.
That’s why the numeric prefixes (e.g., 00-, 10-, 99-) are not cosmetic.
They enforce a predictable order:
- Exports first (env vars)
- Paths early (
PATH,MANPATH, etc.) - Functions before aliases (aliases can call functions)
- Toolchains before project aliases (so commands exist)
- Prompt last (so it can reference everything loaded above)
If you don’t control order, you’ll get “works on some terminals, breaks on others” behavior.
Why this makes your setup safer (especially with AI tools)
1) Reduced blast radius
If a tool mangles 20-nvm.zsh, your history settings, PATH setup, aliases, and prompt don’t disappear.
2) Easier diffs and recovery
A one-file change is easy to review, revert, or rebuild.
3) Cleaner mental model
Each file is a category, not a scavenger hunt.
4) Better automation boundaries
You can tell tools:
“Only touch
20-nvm.zsh.”
Instead of letting them rewrite your entire shell startup.
A practical starting template
If you already have something like this in your .zshrc:
source ~/.zsh.d/exports.zsh
source ~/.zsh.d/paths.zsh
source ~/.zsh.d/functions.zsh
source ~/.zsh.d/nvm.zsh
source ~/.zsh.d/aliases.zsh
source ~/.zsh.d/aliases-proj1.zsh
source ~/.zsh.d/aliases-proj2.zsh
source ~/.zsh.d/aliases-proj3.zsh
source ~/.zsh.d/aliases-proj4.zsh
source ~/.zsh.d/keys.zsh
source ~/.zsh.d/prompt.zsh
You can replace that entire block with the safe loader loop, then rename files with numeric prefixes to keep the order stable.
Backup and management tips
Modularizing reduces risk, but backups make recovery trivial.
There are full dotfile management tools out there (like GNU Stow, chezmoi, yadm), but honestly, a simple automated backup already covers most real-world disasters.
One lightweight approach: regularly zip your shell config folder.
Example: cron-based backup
Create a small backup script:
#!/bin/bash
BACKUP_DIR="$HOME/.dotfile_backups"
SOURCE_DIR="$HOME/.zsh.d"
TIMESTAMP=$(date +"%Y-%m-%d_%H-%M-%S")
mkdir -p "$BACKUP_DIR"
zip -r "$BACKUP_DIR/zshd-backup-$TIMESTAMP.zip" "$SOURCE_DIR" >/dev/nullSave it as backup-zshd.sh, make it executable:
chmod +x ~/backup-zshd.shThen add a cron job:
crontab -eExample entry (daily backup at 3am):
0 3 * * * /Users/yourname/backup-zshd.shNow even if a bad edit wipes a module, you can restore yesterday’s version in seconds.
Final note
AI tools are powerful. That’s the point.
So treat your dotfiles like production config:
- small modules
- clear order
- predictable behavior
- minimal blast radius
Your future self will thank you the next time a “quick fix” tries to become a hard reset.
