update MACHINE-CONTEXT.md — add ERROR REPORT section so Claude Code gives full diagnostic to ML Intern
Browse files- MACHINE-CONTEXT.md +53 -3
MACHINE-CONTEXT.md
CHANGED
|
@@ -50,12 +50,58 @@ system_profiler SPMemoryDataType | head -5
|
|
| 50 |
|
| 51 |
---
|
| 52 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 53 |
## API VERIFICATION (Claude Code: test before ML Intern uses any API)
|
| 54 |
|
| 55 |
When ML Intern says "I want to use [API X]", Claude Code:
|
| 56 |
-
1. Write a minimal test (5-10 lines)
|
| 57 |
2. Compile and run it
|
| 58 |
-
3. Report: works / doesn't work / crashes
|
| 59 |
|
| 60 |
### Verified APIs:
|
| 61 |
| API | Works? | Notes |
|
|
@@ -102,7 +148,9 @@ find ~/Library/Audio/Plug-Ins/VST3/PluginBridge.vst3 -name "PluginBridgeHelper"
|
|
| 102 |
4. ML Intern: reads this file, writes code KNOWING it works on the target machine
|
| 103 |
5. ML Intern: pushes code to HF repo
|
| 104 |
6. Claude Code: pulls, builds, tests, updates this file with results
|
| 105 |
-
7.
|
|
|
|
|
|
|
| 106 |
```
|
| 107 |
|
| 108 |
---
|
|
@@ -115,3 +163,5 @@ find ~/Library/Audio/Plug-Ins/VST3/PluginBridge.vst3 -name "PluginBridgeHelper"
|
|
| 115 |
- **ObjC++ (.mm) files** — only use if Claude Code confirms the ObjC API is available in current SDK
|
| 116 |
- **Window management on macOS** — always ask Claude Code to test the specific approach (fullscreen is tricky)
|
| 117 |
- **JUCE version matters** — APIs change between JUCE 7 and 8. Claude Code can check `JUCE/modules/` headers
|
|
|
|
|
|
|
|
|
| 50 |
|
| 51 |
---
|
| 52 |
|
| 53 |
+
## ERROR REPORT (Claude Code: fill this when something doesn't work)
|
| 54 |
+
|
| 55 |
+
When ML Intern's code fails, Claude Code provides ALL of the following:
|
| 56 |
+
|
| 57 |
+
### Build Errors
|
| 58 |
+
```
|
| 59 |
+
[Full compiler error — not just the first line. Include 5 lines of context above and below.]
|
| 60 |
+
[The exact file and line number]
|
| 61 |
+
[What the code is trying to do at that line]
|
| 62 |
+
```
|
| 63 |
+
|
| 64 |
+
### Runtime Errors
|
| 65 |
+
```
|
| 66 |
+
[Exact behavior: what user sees, what should happen instead]
|
| 67 |
+
[Ableton log output (grep for relevant keywords)]
|
| 68 |
+
[Helper process state (running? crashed? exit code?)]
|
| 69 |
+
[Console output if running Helper manually]
|
| 70 |
+
```
|
| 71 |
+
|
| 72 |
+
### Logic Errors (it runs but does the wrong thing)
|
| 73 |
+
```
|
| 74 |
+
[What was expected to happen]
|
| 75 |
+
[What actually happened]
|
| 76 |
+
[DBG output from the code path (add prints if needed)]
|
| 77 |
+
[Variable values at the point of failure]
|
| 78 |
+
```
|
| 79 |
+
|
| 80 |
+
### Claude Code's Own Analysis
|
| 81 |
+
```
|
| 82 |
+
[What Claude Code thinks is wrong — its best guess at root cause]
|
| 83 |
+
[What it already tried that didn't work]
|
| 84 |
+
[What APIs it verified work/don't work]
|
| 85 |
+
[Relevant Apple documentation or JUCE header info it found]
|
| 86 |
+
```
|
| 87 |
+
|
| 88 |
+
### Minimal Reproduction
|
| 89 |
+
```
|
| 90 |
+
[The smallest code snippet that reproduces the issue]
|
| 91 |
+
[Tested independently outside the full project if possible]
|
| 92 |
+
[Expected output vs actual output]
|
| 93 |
+
```
|
| 94 |
+
|
| 95 |
+
**DO NOT just report "it doesn't work." Always provide the above.**
|
| 96 |
+
|
| 97 |
+
---
|
| 98 |
+
|
| 99 |
## API VERIFICATION (Claude Code: test before ML Intern uses any API)
|
| 100 |
|
| 101 |
When ML Intern says "I want to use [API X]", Claude Code:
|
| 102 |
+
1. Write a minimal standalone test (5-10 lines)
|
| 103 |
2. Compile and run it
|
| 104 |
+
3. Report: works / doesn't work / crashes / returns what value
|
| 105 |
|
| 106 |
### Verified APIs:
|
| 107 |
| API | Works? | Notes |
|
|
|
|
| 148 |
4. ML Intern: reads this file, writes code KNOWING it works on the target machine
|
| 149 |
5. ML Intern: pushes code to HF repo
|
| 150 |
6. Claude Code: pulls, builds, tests, updates this file with results
|
| 151 |
+
7. If error: Claude Code fills ERROR REPORT section with full diagnostic
|
| 152 |
+
8. ML Intern reads diagnostic, writes fix based on FACTS not guesses
|
| 153 |
+
9. Repeat until working
|
| 154 |
```
|
| 155 |
|
| 156 |
---
|
|
|
|
| 163 |
- **ObjC++ (.mm) files** — only use if Claude Code confirms the ObjC API is available in current SDK
|
| 164 |
- **Window management on macOS** — always ask Claude Code to test the specific approach (fullscreen is tricky)
|
| 165 |
- **JUCE version matters** — APIs change between JUCE 7 and 8. Claude Code can check `JUCE/modules/` headers
|
| 166 |
+
- **Never push more than ONE conceptual change at a time** — if it breaks, you know exactly what caused it
|
| 167 |
+
- **If you don't know why something failed, DON'T GUESS** — ask Claude Code to investigate and fill the error report
|