Vibe Coding Methodology · Section 5

The Debugging Iron Rule: Log First, Then Fix

When AI hits an error, its first instinct is to guess a cause and try a fix, then guess another if it fails. This section establishes the most fundamental rule: no guesswork fixes. The two demos below let you compare the two bug-fixing paths hands-on.

Core Rule

No guesswork fixes. When the root cause cannot be confirmed, you must first validate your hypothesis through logs, breakpoints, or test scripts. "Let me just try changing this and see" is forbidden. Backend logs go to the terminal; frontend logs go to the browser Console. For any problem, the first step is always: add logs.

Interactive Demo 1 · Same Bug, Two Approaches
Bug scene: In the chat input box under a Chinese IME, when the user presses Enter to confirm a candidate word, the half-typed pinyin is sent as a message.

Click a path to observe the fix process. The counters on the right track the number of rounds and cumulative lines changed.

0
Fix Rounds
0
Lines Changed
Pending
Bug Status
Select a path above to begin

Guesswork Fix · Results

Not yet demonstrated

Log First, Then Fix · Results

Not yet demonstrated
Interactive Demo 2 · Pre-Fix Three-Question Checklist
New Bug arrived: After the user deletes a chat message, the unread count on the conversation list does not update.

The rule requires answering three questions before fixing any bug. Open each question in order — only after reading all three will the "Start Fix" button unlock.

The chain is delete message → update conversation summary → recalculate unread count → push list refresh. Investigation found that "recalculate unread count" is only triggered when a new message arrives; the delete path never reaches it at all. Staring only at the error point will never reveal this chain.
Changing the recalculation timing will affect three areas: conversation list, app badge, and multi-device message sync. Understand the upstream/downstream dependencies before acting — avoid fixing one thing and breaking another. The rule also recommends: launch a SubAgent to investigate the impact scope in parallel, and only modify after confirming it is safe.
Yes. "Mark as read" and "retract message" follow the same update chain and also missed triggering the recalculation. The same pitfall is rarely in just one place — fix them all this time.

Pre-fix research complete — proceed. After fixing, there is one last step: declare the impact scope so everyone knows what to regression-test.

⚡ Impact scope: conversation list unread count, app badge, mark as read, retract message
Delivery Gate · Two Hard Checks

No Mock to Bypass Real AI Interfaces

For any feature involving AI model calls, confirm the interface is truly accessible before delivery. If the user has not provided an API Key, stop and ask for it — hardcoding fake responses or local mocks to bypass the real call is forbidden. Once the key is in place, send a test request to verify it works before continuing development.

No Delivery Without Passing Unit Tests

Cover core business logic, API interfaces, data processing functions, and edge cases. Test files go in tests/, named test_{module_name}.py; Python projects use pytest. Temporary scripts used for debugging must be deleted after use.

Key Takeaways

Evidence first. The 2 minutes spent adding logs saves three rounds of guesswork rework and prevents the root cause from being buried. After fixing, declare the impact scope in the format ⚡ Impact scope: XXX, YYY, ZZZ, and pass both the real interface check and unit tests before delivery.

Source: this section is adapted from chapter 8 "Debugging and Logging Standards" of rule-opensource.mdc in the open-source repository itshen/xs_vibe_rules.