docs: mandate Linux CLI tools for file editing over internal tools

Added requirement for AI agents to use standard Linux command-line
tools (sed, awk, grep, patch, cut, etc.) instead of internal text
editing functions.

Rationale:
- Internal editing tools fail frequently with whitespace/encoding issues
- Command-line tools are deterministic and well-tested
- Better error messages and easier verification workflow

Changes:
- AGENTS.md: Added "File Editing Requirements" section with tool usage
- SDLC.md: Added "File Editing Standards" section with patterns

Reference: User feedback that internal editing tools "fail way too much"

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
2026-02-20 09:31:23 -05:00
parent aedaabf82c
commit 48d635d8cc
2 changed files with 121 additions and 0 deletions

View File

@@ -434,3 +434,63 @@ Assisted-by: <AI-Model> via Crush <crush@charm.land>
**Last Updated**: 2026-02-19
**SDLC Enforcement**: Pre-commit hook + mandatory workflow documentation
---
## File Editing Requirements
### Use Linux Command-Line Tools (MANDATORY)
**When editing files, prefer Linux command-line tools over internal editing functions.**
**Preferred Tools:**
- `sed` - Stream editor for text transformations
- `awk` - Pattern scanning and processing
- `grep` - Search and filter text
- `patch` - Apply diff files
- `cut` - Remove sections from lines
- `tr` - Translate/delete characters
- `head`/`tail` - Output first/last lines
- `sort`/`uniq` - Sort and deduplicate
- `xargs` - Build command lines from input
**When to Use Each:**
```bash
# Replace text in file
sed -i 's/old/new/g' file.txt
# Replace on specific line
sed -i '42s/old/new/' file.txt
# Append after line matching pattern
sed -i '/pattern/a\new line' file.txt
# Delete lines matching pattern
sed -i '/pattern/d' file.txt
# Extract specific column
awk '{print $2}' file.txt
# Process based on condition
awk '/pattern/ {print $1, $3}' file.txt
# Search and replace with regex
sed -i -E 's/pattern/replacement/g' file.txt
# Apply a patch
patch -p1 < changes.diff
```
**Why This Matters:**
- Internal editing tools fail frequently with whitespace/encoding issues
- Command-line tools are deterministic and well-tested
- Easier to verify changes before applying
- Better error messages when something goes wrong
- Can preview changes with `sed 's/old/new/g' file` (no -i) first
**Workflow:**
1. Read file first: `cat file.txt` or `head -n 50 file.txt`
2. Preview change: `sed 's/old/new/g' file.txt` (no -i)
3. Apply change: `sed -i 's/old/new/g' file.txt`
4. Verify: `git diff file.txt`