Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: trim redundant content from CLAUDE.md (#1958)

Maximilian Roos79dd4d28cf0c
diff --git a/CLAUDE.md b/CLAUDE.md
index c011f3e87..89028e034 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,19 +20,9 @@ We are in **maturing** mode:
**External interfaces to protect:**
- **Config file format** (`wt.toml`, user config) — avoid breaking changes; provide migration guidance when necessary
-- **CLI flags and arguments** — use deprecation warnings; retain old flags for at least one release cycle
+- **CLI flags and arguments** — use deprecation warnings
-**Internal changes remain flexible:**
-- Codebase structure, dependencies, internal APIs
-- Human-readable output formatting and messages
-- Log file locations and formats
-
-When making decisions, prioritize:
-1. **Best technical solution** over backward compatibility
-2. **Clean design** over maintaining old patterns
-3. **Modern conventions** over legacy approaches
-
-Use deprecation warnings to get there smoothly when external interfaces must change.
+Everything else (internal APIs, output formatting, log locations) is flexible. Prefer the best technical solution; use deprecation warnings when external interfaces must change.
## Terminology
@@ -216,17 +206,7 @@ let output = Cmd::new("git")
### Real-time Output Streaming
-Stream command output in real-time — never buffer:
-
-```rust
-// ✅ GOOD - streaming
-for line in reader.lines() {
- println!("{}", line);
- stdout().flush();
-}
-// ❌ BAD - buffering
-let lines: Vec<_> = reader.lines().collect();
-```
+Responsiveness is a priority — stream command output line-by-line rather than buffering.
### Structured Output Over Error Message Parsing
@@ -260,20 +240,11 @@ When no structured alternative exists, document the fragility inline.
## Background Operation Logs
-All background logs are centralized in `.git/wt/logs/` (main worktree's git directory):
+All background logs are centralized in `.git/wt/logs/` (main worktree's git directory). Same operation on same branch overwrites the previous log.
- **Post-start commands**: `{branch}-{source}-post-start-{command}.log` (source: `user` or `project`)
- **Background removal**: `{branch}-remove.log`
-Examples: `feature-user-post-start-npm.log`, `feature-project-post-start-build.log`, `bugfix-remove.log`
-
-### Log Behavior
-
-- **Centralized**: All logs go to main worktree's `.git/wt/logs/`, shared across all worktrees
-- **Overwrites**: Same operation on same branch overwrites previous log (prevents accumulation)
-- **Not tracked**: Logs are in `.git/` directory, which git doesn't track
-- **Manual cleanup**: Stale logs from deleted branches persist but are bounded by branch count
-
## Coverage
**NEVER merge a PR with failing `codecov/patch` without explicit user approval.** The check is marked "not required" in GitHub but it requires user approval to merge. When codecov fails:
@@ -368,9 +339,7 @@ if worktree.is_dirty() {
- **Use `bail!`** for business logic errors (dirty worktree, missing branch, invalid state)
- **Use `.context()`** for wrapping I/O and external command failures
-- **Never `.expect()` or `.unwrap()` in functions returning `Result`** — use `?`, `bail!`, or return an error. Panics in fallible code bypass error handling.
-- **Don't `logger.error` before raising** — include context in the error message itself
-- **Let errors propagate** — don't catch and re-raise without adding information
+- **Never `.expect()` or `.unwrap()` in functions returning `Result`** — use `?`, `bail!`, or return an error
## Config Deprecation
@@ -429,20 +398,7 @@ Function prefixes signal return behavior and side effects.
| `fetch_*` | `Result<T>` | Network I/O | Errors on failure | `fetch_pr_info()`, `fetch_mr_info()` |
| `load_*` | `Result<T>` | File I/O | Errors on failure | `load_project_config()`, `load_template()` |
-**When to use each:**
-
-- **Bare nouns** — Value may not exist and that's fine (Rust stdlib convention)
-- **`set_*`** — Write state to storage
-- **`require_*`** — Value must exist for operation to proceed
-- **`fetch_*`** — Retrieve from external service (network)
-- **`load_*`** — Read from filesystem
-
-**Anti-patterns:**
-
-- Don't use bare nouns if the function makes network calls (use `fetch_*`)
-- Don't use bare nouns if absence is an error (use `require_*`)
-- Don't use `load_*` for computed values (use bare nouns)
-- Don't use `get_*` prefix — use bare nouns instead (Rust convention)
+Don't use `get_*` — bare nouns follow Rust stdlib convention.
## Repository Caching