codebase overhaul (#697)

1 files changed, 35 insertions, 0 deletions

diff --git a/.cursor/rules/comments.mdc b/.cursor/rules/comments.mdc
new file mode 100644
index 00000000..e732e859
--- /dev/null
+++ b/.cursor/rules/comments.mdc
@@ -0,0 +1,35 @@
+---
+alwaysApply: true
+---
+
+# Comment Guidelines
+
+## Good Comments (Human-style)
+- Explain WHY, not WHAT
+- Document non-obvious behavior or edge cases
+- Warn about performance implications or side effects
+- Explain business logic that isn't clear from code
+
+Examples:
+```javascript
+// transfer, not copy; sender buffer detaches
+// satisfies: check shape; keep literals  
+// keep multibyte across chunks
+// timingSafeEqual throws on length mismatch
+```
+
+## Bad Comments (AI-style)
+- Don't explain what the code literally does
+- Don't add changelog-style comments in code
+- Don't comment every line or obvious operations
+
+Avoid:
+```javascript
+// Prevent duplicate initialization
+// Check if project is already loaded  
+// Mark as initializing to prevent race conditions
+// (changed from blah to blah)
+```
+
+## Rule
+Only add comments when there's genuinely non-obvious behavior, performance considerations, or business logic that needs context. Code should be self-documenting through naming and structure.
\ No newline at end of file