- Installation: Use
./dotfilesdirectly (no mise required) - Development: Use
misefor lint, test, and debug tasks - No mise tasks for apply: Removed - use
./dotfilesdirectly - Always respond in pt-BR (Portuguese Brazilian)
- Keep README.md updated: Always update README.md when making changes that affect usage, commands, or project structure
- Linting: All scripts must pass
mise run lint - Quoting: Always quote variables:
"$VAR"not$VAR - Pattern matching: Quote expansions in
${..}:"${var%-"${OS}"}" - Source files: Use
# shellcheck disable=SC1091for optional sources - Continue: Only use
continuein loops - Grep: Use
grep -qinstead of[ -n "$(grep ...)" ] - Redirects: Group multiple redirects:
{ cmd1; cmd2; } >> file - Project utilities: Scripts in
home/.bin/can use any utility installed by the project (e.g.,sd,bat,rg,fd, etc.) - they are installed in the environment before scripts are copied
- Never copy
.gitconfig-guior.gitconfig-noguito home - Only create
.gitconfig- assembled from base + gui/nogui - Skip in copy loops:
if [[ "$filename" == ".gitconfig"* ]]; then continue; fi - Auto-detect GUI: Based on
DISPLAY/WAYLAND_DISPLAYor macOS
- Use
nogui(notno-gui) for consistency - OS suffixes:
-macosand-linux - Keep suffix files:
.bash_profile-${OS},.shared_shell_config-${OS}
- Use
$MISE_CONFIG_ROOTdirectly (no fallback needed) - Always cleanup containers on exit (trap EXIT INT TERM)
- Use process substitution:
< <(find ...)to avoid subshell issues
- Tasks in
.config/mise/tasks/using directory structure _defaultfiles for main tasks with subtasks- No default for debug tasks (must specify gui/nogui)
- Use Docker containers (Ubuntu for GUI, Debian slim for nogui)
- Test
apply:filesonly (not config/install - require sudo) - Verify files copied and
.gitconfigconfiguration
debug:linux:gui: Ubuntu with VNC server (port auto-detected)debug:linux:nogui: Debian slim without GUI- Always cleanup container on bash exit
- VNC password:
password(default)
OS=$(uname)
if [ "$OS" = "Darwin" ]; then
CURRENT_OS="macos"
else
CURRENT_OS="linux"
fiHAS_GUI=false
if [ -n "$DISPLAY" ] || [ -n "$WAYLAND_DISPLAY" ]; then
HAS_GUI=true
elif [[ "$(uname)" == "Darwin" ]]; then
HAS_GUI=true # macOS always has GUI
ficleanup() {
docker rm -f "$CONTAINER_NAME" > /dev/null 2>&1 || true
}
trap cleanup EXIT INT TERM- No macOS automated tests - Only manual testing
- No GitHub Actions for macOS - Not worth the complexity
- Docker for Linux only - Can't test macOS in containers
- mise is optional - Only needed for development tasks
- Always use
./dotfilesfor installation - It's the recommended method
- All scripts must pass shellcheck
- Fix all errors (SC2105, SC2086, SC2143, etc.)
- Use shellcheck disable comments only when necessary
- Check mise tasks too (not just bin/ scripts)
- SC2016 with sd/rg: When using
sdorrgwith single quotes for regex patterns, use# shellcheck disable=SC2016- this is expected and safe - Shellcheck configuration:
.shellcheckrcin project root documents expected patterns
Este AGENTS.md é a fonte única da verdade para qualquer assistente de IA.
CLAUDE.md é um ponteiro fino que aponta pra cá. Codex CLI (OpenAI) e
Antigravity (Google) leem AGENTS.md nativamente (escaneando do CWD até a
raiz do repo) — sem symlink.
Regras always_on lidas pelos assistentes. São a fonte comum de comportamento:
| Rule | Purpose |
|---|---|
001-golden-rule.md |
Always read AGENTS.md |
002-no-destructive.md |
Blocks destructive commands (rm -rf, force push, chmod -R) |
003-language.md |
Reply in pt-BR; repo docs/comments/commits in English |
004-dotfiles-mise.md |
Install via ./dotfiles, dev via mise (file-based tasks) |
005-git-push.md |
git push only when the user explicitly asks |
Cada ferramenta versiona no repo suas permissões e hooks (sem config global). O Claude é a referência; Codex e Antigravity espelham.
| Ferramenta | Arquivo(s) | allow (roda sem prompt) | deny (bloqueia) |
|---|---|---|---|
| Claude Code | .claude/settings.json |
permissions.allow |
permissions.deny |
| Codex CLI | .codex/config.toml + .codex/rules/*.rules |
sandbox_mode="workspace-write" + approval_policy="on-request" |
execpolicy prefix_rule(decision="forbidden") |
| Antigravity | .antigravity/settings.json |
toolPermission="proceed-in-sandbox" + permissions.allow |
permissions.deny (command(...)) |
Deny comum aos três: git push --force/-f/--force-with-lease,
git commit --no-verify, rm -rf /, rm -rf .git, docker system prune. O git push
normal é permitido, mas por regra (005-git-push.md) só quando o usuário pedir. No
Codex, teste as regras com:
codex execpolicy check --rules .codex/rules/default.rules -- <comando>O Codex só lê o
.codex/config.tomldepois que você dá trust na pasta (ele pergunta no 1º run). Não há MCP servers configurados (o dotfiles é um projeto shell standalone — o Claude também não tem.mcp.json).
O Claude roda .claude/hooks/lint.sh (shellcheck no arquivo editado) no
PostToolUse; o Codex replica em .codex/hooks/lint.sh (matcher
apply_patch, registrado no .codex/config.toml). O Antigravity (fork do
VS Code) já faz lint nativo. Em todos, o lint completo continua no
mise run lint, e o hook é só o feedback rápido a cada edição.