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:
60
AGENTS.md
60
AGENTS.md
@@ -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`
|
||||
|
||||
|
||||
61
docs/SDLC.md
61
docs/SDLC.md
@@ -390,3 +390,64 @@ md5sum -c knel-football-secure.iso.md5
|
||||
|
||||
**Copyright © 2026 Known Element Enterprises LLC**
|
||||
**License: GNU Affero General Public License v3.0 only**
|
||||
|
||||
---
|
||||
|
||||
## File Editing Standards
|
||||
|
||||
### Linux Command-Line Tools (MANDATORY for AI Agents)
|
||||
|
||||
**AI agents MUST use standard Linux command-line tools for file editing, not internal text editing functions.**
|
||||
|
||||
**Rationale:** Internal editing tools frequently fail due to:
|
||||
- Whitespace encoding mismatches (tabs vs spaces)
|
||||
- Line ending differences (CRLF vs LF)
|
||||
- Unicode/encoding issues
|
||||
- Exact text matching requirements that are brittle
|
||||
|
||||
**Approved Tools:**
|
||||
| Tool | Use Case |
|
||||
|------|----------|
|
||||
| `sed` | Search/replace, line insertions/deletions |
|
||||
| `awk` | Field extraction, conditional processing |
|
||||
| `grep` | Pattern matching, filtering |
|
||||
| `patch` | Apply diff/patch files |
|
||||
| `cut` | Column extraction |
|
||||
| `tr` | Character translation |
|
||||
| `head`/`tail` | Preview file sections |
|
||||
| `sort`/`uniq` | Sort and deduplicate |
|
||||
|
||||
**Standard Patterns:**
|
||||
|
||||
```bash
|
||||
# In-place text replacement
|
||||
sed -i 's/old_text/new_text/g' file.txt
|
||||
|
||||
# Replace on specific line number
|
||||
sed -i '42s/old/new/' file.txt
|
||||
|
||||
# Insert line after match
|
||||
sed -i '/pattern/a\new_line' file.txt
|
||||
|
||||
# Delete matching lines
|
||||
sed -i '/pattern/d' file.txt
|
||||
|
||||
# Multi-line replacement with extended regex
|
||||
sed -i -E 's/pattern/replacement/g' file.txt
|
||||
|
||||
# Extract specific field (whitespace-delimited)
|
||||
awk '{print $2}' file.txt
|
||||
|
||||
# Conditional processing
|
||||
awk '/pattern/ {print $1}' file.txt
|
||||
|
||||
# Preview changes BEFORE applying (no -i flag)
|
||||
sed 's/old/new/g' file.txt | head -20
|
||||
```
|
||||
|
||||
**Verification Workflow:**
|
||||
1. Read file: `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 result: `git diff file.txt`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user