docs: optimize CLAUDE.md with enhanced directives#160
Conversation
- Add comprehensive Git workflow section (branch/commit/push protocols) - Add File Operations section with tool priority hierarchy - Add Decision Trees for common scenarios - Expand examples with step-by-step workflow - Consolidate standards into clearer subsections - Add protected files list (paru.conf, makepkg.conf) - Improve formatting and structure for better readability Result: More actionable guidance ∴ Explicit protocols for git, file ops, and decision-making
|
🤖 Hi @Ven0m0, I've received your request, and I'm working on it now! You can track my progress in the logs for more details. |
Summary of ChangesHello @Ven0m0, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the CLAUDE.md documentation, transforming it into a more explicit and actionable guide for AI agents managing dotfiles. The changes introduce structured protocols for Git operations, file handling, and decision-making, aiming to provide clearer directives and improve the overall utility and readability of the document. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
The pull request significantly enhances the CLAUDE.md document by introducing comprehensive sections on Git workflow, file operations, and decision trees. The expanded examples and improved formatting contribute to a much clearer and more actionable set of directives for managing dotfiles. The restructuring effectively consolidates information into logical subsections, greatly improving the document's overall readability and utility.
| 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 |
There was a problem hiding this comment.
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.
| ## Example | ||
| ### Fetch/Pull | ||
| - **Specific:** `git fetch origin <branch>` (avoid bare `git fetch`) | ||
| - **Retry:** 4× with backoff on network errors |
There was a problem hiding this comment.
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.
| - **Retry:** 4× with backoff on network errors | |
| - **Retry:** 4× with backoff (2s, 4s, 8s, 16s) on network errors only |
There was a problem hiding this comment.
Pull request overview
This pull request significantly enhances the CLAUDE.md documentation by restructuring and expanding operational directives for Claude AI when working with this dotfiles repository. The changes transform a compact reference into a comprehensive operational manual with explicit protocols and decision-making guidance.
Changes:
- Adds comprehensive Git workflow section with branch naming conventions, commit protocols, and retry logic
- Introduces File Operations section with explicit tool priority hierarchy and edit rules
- Adds Decision Trees section to guide common scenario decision-making (Bash vs Tools, Create vs Edit, When to Refactor)
- Expands examples with step-by-step workflow demonstrations
- Consolidates existing standards into clearer, more organized subsections
- Updates Protected Files list to include
paru.confandmakepkg.conf
| ### Push Protocol | ||
| - **Command:** `git push -u origin <branch-name>` | ||
| - **Retry:** 4× with backoff (2s, 4s, 8s, 16s) on network errors only | ||
| - **Validation:** Branch must start with `claude/` and match session ID |
There was a problem hiding this comment.
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.
| - **Validation:** Branch must start with `claude/` and match session ID | |
| - **Validation:** Branch name must start with `claude/` |
| 5. **Bash:** ONLY for git, package managers, system commands | ||
|
|
||
| ### Edit Rules | ||
| - **Always:** Read file FIRST (Edit/Write tools require it) |
There was a problem hiding this comment.
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.
| - **Always:** Read file FIRST (Edit/Write tools require it) | |
| - **Always:** Read file FIRST when content is unknown or to verify current state |
| `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 |
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
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.
| 5. **Bash:** ONLY for git, package managers, system commands | |
| 5. **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) |
There was a problem hiding this comment.
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.
| - **Edit:** File exists in repo (99% of cases) | |
| - **Edit:** When file exists in repo (always verify first) |
Result: More actionable guidance ∴ Explicit protocols for git, file ops, and decision-making