Elgato_dark/orca
1
0
Fork 0
mirror of https://github.com/stablyai/orca synced 2026-04-21 14:17:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
orca/CLAUDE.md
Jinjing 333023fb67
feat: show merge conflicts in source control sidebar (#204) 
* Squashed commits

- refactor

- commit design doc

* docs: add why-comments to conflict resolution code and track conflicts on open

- Add explanatory comments throughout conflict resolution code covering
  safety constraints, architectural boundaries, and compatibility choices
- Track unresolved conflicts in openConflictFile so Resolved locally
  state works for conflict-safe entry point
- Add CLAUDE.md/AGENTS.md guideline for documenting the "why"
- Add test for conflict tracking through openConflictFile
2026-03-29 15:40:23 -07:00

1.4 KiB
Raw Blame History

CLAUDE.md

See also: AGENTS.md for agent-specific rules.

Code Comments: Document the "Why"

When implementing behavior driven by a design doc, spec, or non-obvious constraint, add a comment explaining why the code does what it does — not just what it does. This is especially important for:

  • Safety constraints — e.g., suppressing an action because it could silently erase a signal, re-create a conflict, or mislead the user.
  • Fallback/error-handling choices — e.g., defaulting to 'modified' on fs error because it's the least misleading option.
  • Architectural boundaries — e.g., why state lives in the renderer and never crosses IPC, or why a feature belongs to Source Control and not Checks.
  • Compatibility shims — e.g., when a field exists purely for downstream plumbing and does not carry semantic meaning.
  • Intentional omissions — e.g., skipping submodule conflicts or not providing rename metadata because the data source doesn't support it.

A future maintainer who hasn't read the design doc should be able to understand from the comment alone why the code must not be changed casually.

Package Manager

This project uses pnpm. Never use npm or yarn.

  • Use pnpm install (not npm install)
  • Use pnpm add <pkg> (not npm install <pkg>)
  • Use pnpm run <script> (not npm run <script>)
  • The lock file is pnpm-lock.yaml. Do not generate package-lock.json or yarn.lock.