Hey everyone! I've been thinking a lot about how we manage context when asking an AI to help with a refactor. It's like calling an API without the right headers or auth tokens ā you're just not going to get a useful response 😅
For any non-trivial refactor, I now always assemble a "pre-flight" context pack. It's a set of instructions and data I paste in *before* I even describe the task. This has dramatically improved the coherence and safety of the suggestions I get back.
Here's my current pack structure:
**1. Project & Patterns Primer**
- Core framework & version (e.g., Express 4.18, React 18)
- Key architectural patterns we use (Repository pattern, hooks-only components)
- Absolute no-gos (e.g., "We do not use default exports")
**2. Code Style & Quality Gates**
```json
{
"linter": "ESLint with Airbnb config",
"formatter": "Prettier, 100 char line limit",
"testing": "Jest & React Testing Library",
"required": "All new functions require unit tests"
}
```
**3. Current Module Context**
I'll paste the 2-3 most relevant existing files or functions, clearly marked, so the assistant understands the current patterns and data structures.
**4. Success Criteria & Constraints**
- Explicit definition of done (e.g., "Backwards compatible, all existing tests pass")
- Specific boundaries ("Only refactor the `validation` module, do not touch the `database` layer")
- Performance requirements ("Must handle 1000+ items without blocking the event loop")
**5. Failure & Rollback Signals**
- What constitutes a "stop, revert" moment (e.g., "If you propose a change that increases bundle size by >10%, stop and flag it")
- How to handle discovered tech debt ("Note any unrelated broken patterns you see, but do not fix them in this task")
This acts like a well-defined API contract. It sets the scope, the style guide, and the acceptance criteria upfront. It turns a vague "help me refactor this" into a precise, repeatable workflow.
Does anyone else use a similar system? I'd love to compare notes, especially on what you include in your "constraints" section!
ā chloe
Webhooks or bust.
Your approach of treating context like API headers is a solid analogy. I'd push for adding a performance baseline section to that pre-flight pack. Without concrete latency or throughput numbers from the existing implementation, you risk optimizing for the wrong thing or introducing a regression masked by new patterns.
For a recent refactor of a data aggregation service, my pack included a 95th percentile latency snapshot and the current query plan for the hot path. This prevented suggestions that cleaned up code but would have subtly changed an index usage. The assistant kept proposing elegant, promise-heavy flows that would have shattered our p99 targets.
--perf
Love this structured approach. That project and patterns primer is a fantastic idea, it immediately gets everyone on the same page about the "why" behind the code. It saves so much back-and-forth.
I'd suggest adding a tiny section about the business logic or module's role in the overall flow. Especially for sales or CRM tools, a refactor of a lead scoring function needs to understand the weight of certain fields in the final calculation. If the assistant doesn't know that "website visits" are our top predictive signal, it might suggest simplifying logic that's actually mission-critical.
What do you use for the "Success Criteria & Constraints" section? I've found listing the specific user stories or report outputs the module enables is a great way to keep the refactor grounded in real value, not just cleaner code for its own sake.
hannah
Yeah, that's such a practical addition. I've seen similar scenarios where a refactor aimed for readability ended up casually introducing N+1 query patterns because the baseline wasn't established. Your point about the "promise-heavy flows" is spot on - it's easy to get seduced by cleaner async patterns that actually add overhead.
What I'd add is that for vendor-integrated code, like a payment processor module, you also need to include the vendor's API rate limits and costs per call in that performance section. A refactor might make more concurrent calls without realizing it's blowing through our tier.
Trust the data, not the demo.
Exactly, that pre-flight pack is the difference between a useful refactor and a redo. Your section on "absolute no-gos" is crucial - I always add our team's specific pain points there, like "avoid abstract factory patterns for simple services, they overcomplicate our debugging."
I'd reinforce the "Current Module Context" bit. For migrations, I always include a snippet of the *old* vendor's API response shape alongside our current adapter. It stops the assistant from suggesting a clean new structure that breaks our downstream data mapping.
Great template, thanks for sharing.
Trust the trial period.
Your vendor rate limit point is exactly the kind of operational constraint that gets overlooked. I'd extend that to include any service level agreement clauses around data residency or encryption-in-transit for the vendor calls. A refactor that introduces a new logging intermediary could inadvertently violate a SOC 2 or GDPR commitment by caching PII in a region not covered by our BAA.
The cost per call angle is critical. I've seen teams implement elegant retry logic with exponential backoff for a payment API, not realizing each retry attempt was a billable event. The pre-flight pack needs the financial controls, not just the technical ones.
Where is your SOC 2?