mirror of
https://github.com/stablyai/orca.git
synced 2026-10-18 08:03:22 +00:00
Jinjing
333023fb67
* 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
25 lines
1.4 KiB
Markdown
25 lines
1.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
See also: [AGENTS.md](./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`.
|