@@ -237,6 +237,40 @@ ESPI uses Atom XML feeds for data exchange. Key patterns:
237237
238238### Common Development Patterns
239239
240+ #### File Modification Best Practices
241+ ** CRITICAL: Always use the Edit tool with visible diffs instead of sed/awk for file modifications**
242+
243+ - ** NEVER use sed, awk, or bash text manipulation** for modifying source code or test files
244+ - ** ALWAYS use the Edit tool** which shows explicit diffs for review
245+ - ** Benefits of Edit tool** :
246+ - Changes are visible and reviewable before execution
247+ - Prevents cascading errors from bulk updates
248+ - Easy to verify correctness with explicit old_string → new_string diff
249+ - Catches errors immediately rather than discovering them during compilation
250+
251+ - ** When multiple files need the same change** :
252+ - Use multiple Edit tool calls (one per file) in a single message
253+ - Show exactly what's changing in each file
254+ - Do NOT use sed/awk loops even if it seems more efficient
255+
256+ - ** Exception** : Only use bash text tools (grep, find) for ** searching/analysis** , never for modifications
257+
258+ ** Example - WRONG approach:**
259+ ``` bash
260+ # DON'T DO THIS - sed makes changes invisibly
261+ sed -i ' ' ' s/OldClass/NewClass/g' src/** /* .java
262+ ```
263+
264+ ** Example - CORRECT approach:**
265+ ```
266+ # DO THIS - Use Edit tool with explicit diffs
267+ Edit tool call showing:
268+ old_string: "import com.example.OldClass;"
269+ new_string: "import com.example.NewClass;"
270+ ```
271+
272+ This practice prevents issues like missing imports, broken references, and compilation errors that are difficult to track down.
273+
240274#### Adding New ESPI Entity
2412751 . Create entity in ` openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/ ` (or ` /customer/ ` )
2422762 . Extend ` IdentifiedObject ` base class
0 commit comments