Cline rules

1# TypeScript Backend Engineering Rules
2 
3## 1. Prefer Strong Typing at Assignment Time
4 
5Avoid late casts using `as` whenever possible.
6 
7### Bad
8 
9```ts
10const data = fn()
11const record = data as Record<string, unknown>
12```
13 
14### Good
15 
16```ts
17const data: Record<string, unknown> = fn()
18```
19 
20### Better
21 
22```ts
23type ProviderPayload = {
24  model?: string
25  stream?: boolean
26  [key: string]: unknown
27}
28 
29const data: ProviderPayload = fn()
30```
31 
32### Rationale
33 
34* Reduces unsafe casts
35* Improves readability
36* Better type inference
37* Reduces temporary variables
38 
39---
40 
41## 2. Prefer Early Returns Over Nested Conditionals
42 
43### Bad
44 
45```ts
46if (x) {
47  if (y) {
48    if (z) {
49      doSomething()
50    }
51  }
52}
53```
54 
55### Good
56 
57```ts
58if (!x) return error()
59if (!y) return error()
60if (!z) return error()
61 
62doSomething()
63```
64 
65### Rationale
66 
67* Reduces cyclomatic complexity
68* Keeps the happy path visible
69* Easier debugging and maintenance
70 
71---
72 
73## 3. Keep HTTP Handlers Thin
74 
75HTTP handlers should orchestrate logic, not implement all logic inline.
76 
77### Bad
78 
79Large handlers containing:
80 
81* validation
82* transformation
83* metrics
84* streaming
85* error handling
86* business logic
87 
88### Good
89 
90```ts
91handleStreamingResponse()
92handleProviderError()
93applyPayloadMiddlewares()
94```
95 
96### Rationale
97 
98* Improves testability
99* Improves maintainability
100* Easier code reuse
101 
102---
103 
104## 4. Centralize Error Handling
105 
106### Bad
107 
108```ts
109if (error instanceof ProviderError) ...
110if (error instanceof ProviderError) ...
111if (error instanceof ProviderError) ...
112```
113 
114### Good
115 
116```ts
117const providerError =
118  error instanceof ProviderError
119    ? error
120    : null
121```
122 
123### Rationale
124 
125* Reduces duplication
126* Simplifies branching
127* Easier future changes
128 
129---
130 
131## 5. Avoid Generic `Record<string, unknown>` When Structure Exists
132 
133### Bad
134 
135```ts
136Record<string, unknown>
137```
138 
139for structured payloads.
140 
141### Good
142 
143```ts
144type ProviderPayload = {
145  model?: string
146  stream?: boolean
147  messages?: unknown[]
148}
149```
150 
151### Rationale
152 
153* Better autocomplete
154* Better developer experience
155* Self-documenting code
156 
157---
158 
159## 6. Keep the Happy Path Readable
160 
161The main execution flow should be easy to scan top-to-bottom.
162 
163### Preferred Structure
164 
165```ts
166parse
167validate
168resolve provider
169transform payload
170apply middlewares
171execute request
172return response
173```
174 
175### Rationale
176 
177Handlers are read far more often than written.
178 
179---
180 
181## 7. Encapsulate Conditional Middleware Logic
182 
183### Bad
184 
185```ts
186if (env.RTK_ENABLED === 'true') { ... }
187if (env.CAVEMAN_ENABLED === 'true') { ... }
188```
189 
190spread across handlers.
191 
192### Good
193 
194```ts
195applyPayloadMiddlewares()
196```
197 
198### Rationale
199 
200* Better encapsulation
201* Easier scaling
202* Cleaner handlers
203 
204---
205 
206## 8. Separate Stream and Non-Stream Flows Early
207 
208### Bad
209 
210Interleaving stream and non-stream logic throughout the handler.
211 
212### Good
213 
214```ts
215return isStream
216  ? handleStreamingResponse(...)
217  : handleJsonResponse(...)
218```
219 
220### Rationale
221 
222* Reduces mental overhead
223* Easier debugging
224* Easier maintenance
225 
226---
227 
228## 9. Reduce Temporary Variables
229 
230### Bad
231 
232```ts
233const a = fn()
234const b = a as SomeType
235```
236 
237### Good
238 
239```ts
240const b: SomeType = fn()
241```
242 
243### Rationale
244 
245* Less visual noise
246* Less state tracking
247* Cleaner code
248 
249---
250 
251## 10. Prefer Focused Helper Functions
252 
253### Good
254 
255```ts
256badRequest()
257handleProviderError()
258handleStreamingResponse()
259applyPayloadMiddlewares()
260```
261 
262### Rationale
263 
264* Improves readability
265* Easier testing
266* Better reuse
267* Smaller diffs in PRs
268 
269---
270 
271## 11. Avoid Repeated Runtime Type Checks
272 
273### Bad
274 
275```ts
276if (typeof x === 'string') ...
277if (typeof x === 'string') ...
278```
279 
280### Good
281 
282Normalize once and reuse.
283 
284```ts
285const message =
286  typeof x === 'string'
287    ? x
288    : 'unknown'
289```
290 
291### Rationale
292 
293* Cleaner control flow
294* Less duplication
295 
296---
297 
298## 12. Prefer Explicit Function Names
299 
300### Bad
301 
302```ts
303handle()
304process()
305run()
306```
307 
308### Good
309 
310```ts
311handleStreamingResponse()
312transformProviderPayload()
313recordMetrics()
314```
315 
316### Rationale
317 
318* Improves discoverability
319* Easier onboarding
320* Easier navigation in large codebases
321 
322---
323 
324## 13. Keep Side Effects Explicit
325 
326Avoid hidden mutations when possible.
327 
328### Bad
329 
330```ts
331modify(payload)
332```
333 
334### Good
335 
336```ts
337const updatedPayload = applyMiddleware(payload)
338```
339 
340Unless mutation is intentionally chosen for performance reasons and clearly documented.
341 
342### Rationale
343 
344* Easier debugging
345* Predictable behavior
346* Better composability
347 
348---
349 
350## 14. Prefer Small Composable Units
351 
352### Bad
353 
354Large 300+ line handlers or services.
355 
356### Good
357 
358Small focused helpers with single responsibility.
359 
360### Rationale
361 
362* Easier testing
363* Easier refactoring
364* Better long-term maintainability
365 
366---
367 
368## 15. Optimize for Readability First
369 
370Readable code is usually more maintainable than clever abstractions.
371 
372### Prefer
373 
374* explicit naming
375* flat control flow
376* predictable structure
377* isolated responsibilities
378 
379### Avoid
380 
381* over-engineering
382* deeply nested abstractions
383* unnecessary generics
384* excessive indirection
385