Skip to content

docs: optimize CLAUDE.md with enhanced directives #160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ven0m0 merged 1 commit into from
Jan 20, 2026
Merged

docs: optimize CLAUDE.md with enhanced directives #160

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 112 additions & 30 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,131 @@
# Repo Manual: Arch/Debian Dotfiles

**Purpose:** Dotfiles management instructions for Claude AI **Model:** claude-\* (all Claude models) **Tone:** Blunt,
precise. `Result ∴ Cause`. Lists ≤7
**Purpose:** Claude AI operational directives for dotfiles repo
**Model:** claude-\* (all) **Tone:** Blunt, precise. `Result ∴ Cause`. Lists ≤7
**System:** YADM (`Home/`→`~/`) + Tuckr (`etc/`,`usr/`→`/`)
**Targets:** Arch (CachyOS), Debian, Termux
**Priority:** User>Rules. Verify>Assume. Edit>Create. Debt-First.

**System:** YADM (`Home/`→`~/`) + Tuckr (`etc/`,`usr/`→`/`). **Targets:** Arch (CachyOS), Debian, Termux.
**Directives:** User>Rules. Verify. Edit>Create (min Δ). Debt-First.
## Core Standards

## Standards
### Bash
- **Header:** `#!/usr/bin/env bash` + `set -euo pipefail`
- **Idioms:** `[[ ]]`, `mapfile -t`, `local -n`, `printf`, `ret=$(fn)`, `${var}`
- **Ban:** `eval`, `ls` parse, backticks, unquoted vars
- **Packages:** `paru`→`yay` (Arch) | `apt` (Debian). Verify with `pacman -Q` first.

- **Bash:** `set -euo pipefail`. `#!/usr/bin/env bash`.
- _Idioms:_ `[[ regex ]]`, `mapfile -t`, `local -n`, `printf`, `ret=$(fn)`.
- _Ban:_ `eval`, `ls` parse, backticks.
- _Pkg:_ `paru`→`yay` (Arch) | `apt` (Debian). Check `pacman -Q` first.
- **Tools:** fd→find | rg→grep | bat→cat | sd→sed | aria2→curl | jaq→jq | rust-parallel.
- **Perf:** Batch I/O. Async. Anchor regex (`grep -F`). Cache hot data.
- **Protected:** `pacman.conf`, `.zshrc`, `.gitconfig`, `sysctl.d/`.
### Tools (Prefer Modern)
fd→find | rg→grep | bat→cat | sd→sed | aria2→curl | jaq→jq | rust-parallel

## Workflow
### Performance
Batch I/O. Parallel ops. Anchor regex (`grep -F`). Cache hot paths. Single-pass parsing.

- **Cycle:** TDD (Red→Green→Refactor). Edit > Create.
- **Sync:** `yadm-sync.sh` (User). `tuckr set etc usr` (Sys).
- **CI:** `lint-format` (shfmt, shellcheck, biome, ruff, actionlint).
- **QA:** Shellcheck + Syntax verify before save.
### Protected Files (Read-Only)
`pacman.conf`, `.zshrc`, `.gitconfig`, `sysctl.d/*.conf`, `paru.conf`, `makepkg.conf`

## Key Assets
## Git Workflow

- **Scripts (`~/.local/bin`):**
- _Sys:_ `pkgui` (TUI), `systool` (maint), `dosudo` (priv), `autostart`.
- _Media:_ `media-opt`, `ffwrap`, `wp`.
- _File/Net:_ `fzgrep`, `fzgit`, `netinfo`, `websearch`.
- _Dev:_ `yadm-sync`, `lint-format`.
- **Configs:** 88 total. Shells (Bash/Zsh/Fish), Terminals, Dev tools (VSCode/Git/Mise).
- **AI:** Claude (Agents/Cmds), Copilot, Gemini (`.gemini/`).
### Branch Management
- **Develop on:** `claude/*` branches (e.g., `claude/optimize-claude-md-K4K9r`)
- **Never:** Push to `main`/`master` without explicit permission
- **Create:** `git checkout -b <branch>` if missing

## Deployment
### Commits
- **Message:** `<action>: <what> [why if non-obvious]` (e.g., `fix: quote vars in systool`)
- **Stage:** Selective (`git add <files>`). Never `-A` without review.
- **Verify:** `git status` + `git diff --staged` before commit

`yadm clone --bootstrap` → Install Pkgs → Deploy Home → Deploy Sys (Tuckr).
### Push Protocol
- **Command:** `git push -u origin <branch-name>`
- **Retry:** 4× with backoff (2s, 4s, 8s, 16s) on network errors only

Copilot AI Jan 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The retry protocol specifies "4× with backoff" but this could lead to very long wait times (2+4+8+16 = 30 seconds total wait time plus actual operation time). For git operations in an interactive AI context, this may be excessive. Consider documenting whether Claude should inform the user about retry attempts, or if a shorter retry sequence would be more appropriate for the use case.

Copilot uses AI. Check for mistakes.
- **Validation:** Branch must start with `claude/` and match session ID

Copilot AI Jan 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The validation requirement that "Branch must start with claude/ and match session ID" is unclear and potentially problematic. What is a "session ID" in this context, and how would Claude verify this match? This could create confusion or block valid git operations. Consider either removing this requirement or clarifying what "session ID" means and how it should be validated.

Suggested change
- **Validation:** Branch must start with `claude/` and match session ID
- **Validation:** Branch name must start with `claude/`

Copilot uses AI. Check for mistakes.

## Example
### Fetch/Pull
- **Specific:** `git fetch origin <branch>` (avoid bare `git fetch`)
- **Retry:** 4× with backoff on network errors

@gemini-code-assist gemini-code-assist Bot Jan 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For consistency and precision, the retry instruction for 'Fetch/Pull' could specify the backoff times, similar to the 'Push Protocol' section. This ensures uniform behavior for network error handling across different Git operations.

Suggested change
- **Retry:** 4× with backoff on network errors
- **Retry:** 4× with backoff (2s, 4s, 8s, 16s) on network errors only


**Task:** Fix script with shellcheck error **Input:** `systool` has unquoted variable **Output:**
## File Operations

### Tool Priority
1. **Read:** `Read` tool (NOT `cat`/`head`/`tail`)
2. **Search:** `Grep`/`Glob` tools (NOT `grep`/`find` commands)
3. **Edit:** `Edit` tool (NOT `sed`/`awk`)
4. **Write:** `Write` tool (NOT `echo >`/heredoc)
5. **Bash:** ONLY for git, package managers, system commands
Comment on lines +50 to +54

@gemini-code-assist gemini-code-assist Bot Jan 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The 'Tool Priority' section introduces abstract tool names (e.g., Read tool, Grep/Glob tools). To enhance clarity and ensure the AI uses the intended modern tools, consider providing examples or direct mappings to the specific tools listed in the 'Tools (Prefer Modern)' section (e.g., bat for Read tool, rg for Grep tool). This would make the directives more actionable and reduce potential ambiguity.

Copilot AI Jan 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instruction specifies "Bash: ONLY for git, package managers, system commands" but then contradicts this in the decision tree at line 101 which says "Bash: git, paru/apt, systemctl, service management". The decision tree provides more specific guidance and should be aligned with the tool priority section. Either add "systemctl, service management" to line 54 or ensure both sections use identical language for consistency.

Suggested change
5. **Bash:** ONLY for git, package managers, system commands
5. **Bash:** git, paru/apt, systemctl, service management

Copilot uses AI. Check for mistakes.

### Edit Rules
- **Always:** Read file FIRST (Edit/Write tools require it)

Copilot AI Jan 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instruction "Read file FIRST (Edit/Write tools require it)" may not be technically accurate for all contexts. The Edit tool can work without first using Read if the file content is already known or if making targeted changes. Consider revising to "Read file FIRST when content is unknown or to verify current state" to be more precise.

Suggested change
- **Always:** Read file FIRST (Edit/Write tools require it)
- **Always:** Read file FIRST when content is unknown or to verify current state

Copilot uses AI. Check for mistakes.
- **Match:** Exact indentation/whitespace from Read output
- **Scope:** Minimum viable change (no refactoring unless requested)
- **Verify:** Shellcheck/syntax before save

## Quality Assurance

### Pre-Save Checks
1. Shellcheck (bash scripts)
2. Syntax validation (all code)
3. Protected file check
4. Git status (uncommitted changes)

### CI Pipeline
`lint-format` runs: shfmt, shellcheck, biome, ruff, actionlint

### Testing
- **Pattern:** TDD (Red→Green→Refactor)
- **Scripts:** Test with target shell + shellcheck
- **Configs:** Validate syntax before deployment

## Sync Operations

- **User configs:** `yadm-sync.sh` (commits & pushes `Home/`→`~/`)
- **System configs:** `tuckr set etc usr` (deploys `/etc`, `/usr`)
- **Bootstrap:** `yadm clone --bootstrap` (full deploy)

## Key Assets (88 configs total)

### Scripts (`~/.local/bin`)
- **Sys:** `pkgui`, `systool`, `dosudo`, `autostart`
- **Media:** `media-opt`, `ffwrap`, `wp`
- **File/Net:** `fzgrep`, `fzgit`, `netinfo`, `websearch`
- **Dev:** `yadm-sync`, `lint-format`

### Configs
- **Shells:** Bash, Zsh, Fish (+ Starship prompt)
- **Terminals:** Alacritty, Kitty, Wezterm
- **Dev:** VSCode, Git, Mise, Neovim
- **AI:** Claude (agents/cmds), Copilot, Gemini

## Decision Trees

### When to use Bash vs Tools?
- **Bash:** git, paru/apt, systemctl, service management
- **Tools:** All file/search operations, text processing

### When to create vs edit?
- **Edit:** File exists in repo (99% of cases)

Copilot AI Jan 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instruction "Edit: File exists in repo (99% of cases)" implies this is the default for almost all scenarios, but the guidance should be more nuanced. Claude should check if the file exists before deciding to edit vs create, not assume based on percentages. Consider revising to "Edit: When file exists in repo (always verify first)" to be more actionable.

Suggested change
- **Edit:** File exists in repo (99% of cases)
- **Edit:** When file exists in repo (always verify first)

Copilot uses AI. Check for mistakes.
- **Create:** New script/config explicitly requested + doesn't exist

### When to refactor?
- **Yes:** Technical debt blocks current task
- **No:** Code works, no user request, "while we're here"

## Examples

### Fix Shellcheck Error
```bash
# Task: systool has unquoted variable
# Before: log_path=$HOME/.cache/systool.log
# After: log_path="${HOME}/.cache/systool.log"
# Result: Shellcheck passes ∴ Variables quoted per standards
```

**Result:** Shellcheck passes ∴ Variables quoted per standards.
### Add Feature to Script
```bash
# Task: Add verbose flag to pkgui
# 1. Read ~/.local/bin/pkgui (Read tool)
# 2. Search for flag parsing (line ~15-30)
# 3. Edit to add -v flag + verbose logic (Edit tool)
# 4. Verify shellcheck passes
# 5. Commit: "feat: add verbose flag to pkgui"
# Result: Feature added ∴ Min change, QA passed
```
Loading