升级Trellis并精简项目知识（09-05-trellis-upgrade-rule-cleanup）
更新Trellis适配、任务归属与归档失败恢复，精简技能入口和知识读取规则。 保留权限、证据、事务及独立复核合同；纳入对应任务及已完成复核记录。 仅本地提交，不启用新平台适配，不推送或部署。
这个提交包含在：
@@ -1,105 +1,21 @@
|
||||
# Code Reuse Thinking Guide
|
||||
|
||||
> **Purpose**: Stop and think before creating new code - does it already exist?
|
||||
Consult when adding a helper/component or changing behavior shared by multiple
|
||||
consumers. Search the relevant source and tests with `rg` before creating a
|
||||
second implementation; widen the search when ownership is uncertain.
|
||||
|
||||
---
|
||||
## Decide From The Contract
|
||||
|
||||
## The Problem
|
||||
- Compare responsibilities, inputs, failure behavior, permissions and lifecycle, not only similar syntax or visual shape.
|
||||
- Reuse or extend an existing owner when the semantics agree. Keep distinct rules separate when combining them creates flags, coupling or misleading names.
|
||||
- Share constants only when they represent the same business fact. A fixed repetition count or similarity percentage does not justify an abstraction.
|
||||
- For a shared change, identify callers and assert the affected behaviors, including exceptions. After a batch edit, check for missed consumers and accidental out-of-scope changes.
|
||||
|
||||
**Duplicated code is the #1 source of inconsistency bugs.**
|
||||
## Asymmetric Producers
|
||||
|
||||
When you copy-paste or rewrite existing logic:
|
||||
- Bug fixes don't propagate
|
||||
- Behavior diverges over time
|
||||
- Codebase becomes harder to understand
|
||||
|
||||
---
|
||||
|
||||
## Before Writing New Code
|
||||
|
||||
### Step 1: Search First
|
||||
|
||||
```bash
|
||||
# Search for similar function names
|
||||
grep -r "functionName" .
|
||||
|
||||
# Search for similar logic
|
||||
grep -r "keyword" .
|
||||
```
|
||||
|
||||
### Step 2: Ask These Questions
|
||||
|
||||
| Question | If Yes... |
|
||||
|----------|-----------|
|
||||
| Does a similar function exist? | Use or extend it |
|
||||
| Is this pattern used elsewhere? | Follow the existing pattern |
|
||||
| Could this be a shared utility? | Create it in the right place |
|
||||
| Am I copying code from another file? | **STOP** - extract to shared |
|
||||
|
||||
---
|
||||
|
||||
## Common Duplication Patterns
|
||||
|
||||
### Pattern 1: Copy-Paste Functions
|
||||
|
||||
**Bad**: Copying a validation function to another file
|
||||
|
||||
**Good**: Extract to shared utilities, import where needed
|
||||
|
||||
### Pattern 2: Similar Components
|
||||
|
||||
**Bad**: Creating a new component that's 80% similar to existing
|
||||
|
||||
**Good**: Extend existing component with props/variants
|
||||
|
||||
### Pattern 3: Repeated Constants
|
||||
|
||||
**Bad**: Defining the same constant in multiple files
|
||||
|
||||
**Good**: Single source of truth, import everywhere
|
||||
|
||||
---
|
||||
|
||||
## When to Abstract
|
||||
|
||||
**Abstract when**:
|
||||
- Same code appears 3+ times
|
||||
- Logic is complex enough to have bugs
|
||||
- Multiple people might need this
|
||||
|
||||
**Don't abstract when**:
|
||||
- Only used once
|
||||
- Trivial one-liner
|
||||
- Abstraction would be more complex than duplication
|
||||
|
||||
---
|
||||
|
||||
## After Batch Modifications
|
||||
|
||||
When you've made similar changes to multiple files:
|
||||
|
||||
1. **Review**: Did you catch all instances?
|
||||
2. **Search**: Run grep to find any missed
|
||||
3. **Consider**: Should this be abstracted?
|
||||
|
||||
---
|
||||
|
||||
## Gotcha: Asymmetric Mechanisms Producing Same Output
|
||||
|
||||
**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
|
||||
|
||||
**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
|
||||
|
||||
**Prevention checklist**:
|
||||
- [ ] When migrating directory structures, search for ALL code paths that reference the old structure
|
||||
- [ ] If one path is auto-derived (glob/copy) and another is manually listed, the manual one needs updating
|
||||
- [ ] Add a regression test that compares outputs from both mechanisms
|
||||
|
||||
---
|
||||
|
||||
## Checklist Before Commit
|
||||
|
||||
- [ ] Searched for existing similar code
|
||||
- [ ] No copy-pasted logic that should be shared
|
||||
- [ ] Constants defined in one place
|
||||
- [ ] Similar patterns follow same structure
|
||||
When automatic discovery/copy and a manually listed producer promise the same
|
||||
output (for example init/update, screen/export or live/snapshot inputs), a
|
||||
rename or added field can update only one side. Inspect both producers and
|
||||
compare their observable output contract. Prefer a focused parity regression
|
||||
over another copied list; do not assume generated output proves every producer
|
||||
was exercised.
|
||||
|
||||
在新工单中引用
屏蔽一个用户