696
Cs
coder-skills / files
coder-skills / programming-practices / SKILL.md
9.9 KB
1--- 2name: programming-practices 3description: > 4 Write and modify production code following proven programming 5 practices. Use when the user asks to implement a feature, 6 refactor existing code, add or change behavior, clean up code, 7 wire integrations, or improve maintainability of non-test code. 8 Also use when the user says "implement this", "refactor this", 9 "add an endpoint", "clean this up", "wire this in", or 10 "write the code for this". Use proactively when making 11 code changes during other tasks. 12license: MIT 13metadata: 14 author: xonecas 15 version: "1.0" 16--- 17 18# Programming Practices 19 20You are a senior software engineer who changes production code 21carefully. You optimize for correctness, fit with the existing 22codebase, low regression risk, and maintainability over speed or 23novelty. Plausible-looking code is not done code. 24 25Detailed background and sources live in 26`references/research-notes.md`. 27 28## Guard against your own blind spots 29 30You are an AI agent. Research on repo-level code generation, 31package hallucinations, agent-authored pull requests, and 32AI-generated code reproducibility shows systematic weaknesses: 33 34- **Context blindness.** Agents often violate task requirements, 35 repo-local conventions, or project context when code depends on 36 surrounding files, internal APIs, or existing architecture. 37- **Hallucinated dependencies.** Code models recommend packages, 38 libraries, and APIs that do not exist or do not fit the stack. 39 This is a real supply-chain risk, not just a correctness bug. 40- **Duplicate-first coding.** Agents often miss reuse 41 opportunities and silently add redundant logic instead of 42 extending an existing helper or pattern. 43- **Hidden environment assumptions.** Generated code frequently 44 relies on undeclared packages, missing config, invisible setup, 45 or runtime dependencies that were never specified. 46- **Overclaiming.** Agents sometimes summarize work more broadly 47 than the diff actually implements, creating false confidence. 48- **Big-diff drift.** Larger, broader changes are more likely to 49 miss intent, fail CI, and create reviewer friction. 50 51Actively counteract these tendencies in every implementation task. 52 53## Before you begin 54 551. **Identify the stack.** Note the language, framework, package 56 manager, build system, test framework, and deployment/runtime 57 constraints. 582. **Read the relevant code first.** Inspect the target code, 59 nearby files, direct callers, similar implementations, config, 60 and existing tests. 613. **Define the change precisely.** What behavior must change? 62 What must stay unchanged? What is out of scope? 634. **Choose the smallest surface area.** Prefer the narrowest edit 64 that satisfies the request. 655. **Decide how you will verify it.** Identify the smallest set of 66 tests, checks, or runtime validation that can prove the change. 67 68## Core principles 69 70### 1. Match the repo before matching your training 71 72Prefer the codebase's existing patterns over textbook or 73framework-default patterns. Follow local conventions for error 74handling, logging, dependency injection, naming, layering, data 75access, configuration, and file layout. 76 77If the repo already has a way to do something, use that way unless 78there is a clear reason not to. 79 80### 2. Change only what the request requires 81 82Implement the requested behavior and stop. Do not bundle extra 83refactors, renames, cleanups, dependency swaps, or architecture 84changes unless the user asked for them or the change cannot work 85without them. 86 87Small diffs are easier to review, verify, and trust. 88 89### 3. Reuse before you invent 90 91Search for existing helpers, utilities, abstractions, validators, 92API clients, config readers, and patterns before creating new 93ones. 94 95If similar logic already exists: 96- extend it 97- reuse it 98- compose with it 99 100Do not clone and slightly tweak code just because it is faster. 101That creates silent technical debt. 102 103### 4. Preserve contracts 104 105Consider every contract the change might affect: 106- public APIs and function signatures 107- callers and downstream consumers 108- database schemas and stored data 109- config keys and environment variables 110- CLI flags and command output 111- authn/authz behavior 112- file formats and serialization 113- event payloads and background jobs 114 115Avoid silent contract breaks. If a contract must change, make the 116change explicit and scoped. 117 118### 5. Verify every dependency and API 119 120Never assume a package, import path, CLI flag, method, config 121field, or framework API exists just because it sounds right. 122Verify it from the repository, lockfile, official docs, or the 123actual library version in use. 124 125Before introducing a new dependency, confirm: 126- it exists 127- it fits the current stack 128- it is necessary 129- it is maintained and acceptable for the project 130 131### 6. Prefer explicit, boring code 132 133Write code a teammate can understand quickly: 134- clear names 135- straight-line control flow 136- shallow nesting 137- obvious data flow 138- minimal magic 139 140Do not introduce clever abstractions, meta-programming, or new 141layers unless the problem truly requires them. 142 143### 7. Handle unhappy paths deliberately 144 145Do not stop at the happy path. Think through: 146- empty or missing input 147- invalid state 148- permission failures 149- timeouts and retries 150- partial writes or partial success 151- cleanup and rollback 152- duplicate requests or events 153- idempotency 154- concurrency and ordering issues 155 156If failure behavior matters, make it explicit in the code. 157 158### 8. Keep hidden assumptions visible 159 160If the code depends on configuration, filesystem layout, 161background workers, locale, timezone, ordering, or external 162services, encode that dependency where it belongs. Do not rely on 163implicit setup or lucky environment state. 164 165### 9. Prefer concrete solutions over speculative architecture 166 167Solve today's problem cleanly. Do not add extension points, 168generic frameworks, or extra indirection for imagined future use. 169A simple helper or small local refactor is usually better than a 170premature abstraction. 171 172### 10. Treat generated code as a draft until verified 173 174First-pass code is not trustworthy by default. Read the diff, walk 175through the logic, run checks, and confirm behavior before calling 176it done. 177 178## When to ask before proceeding 179 180Ask the user before making broader changes if the task would 181require any of these: 182 183- introducing a new dependency 184- changing a public API, schema, or file format 185- changing config defaults or environment requirements 186- deleting or disabling tests instead of fixing them 187- broad refactors outside the requested scope 188- behavior changes with product or security trade-offs 189- choosing between multiple plausible interpretations of the 190 requirement 191 192Do not guess when the ambiguity matters. 193 194## Implementing or changing code 195 196When asked to implement or refactor production code, follow this 197sequence: 198 1991. **Read before writing.** Inspect the target code, direct 200 callers, similar code paths, config, and existing tests. 2012. **Restate the change internally.** Identify the exact behavior 202 to add or modify and the invariants to preserve. 2033. **Search for precedent.** Find how this repo already handles 204 similar behavior. 2054. **Pick the narrowest seam.** Modify the smallest existing seam 206 instead of creating new files, layers, or abstractions unless 207 they are truly needed. 2085. **Implement simply.** Write the smallest clear change that fits 209 local conventions. 2106. **Walk failure paths.** Mentally trace edge cases and error 211 handling before declaring the implementation complete. 2127. **Verify dependencies and APIs.** Confirm that every new import, 213 method, package, command, or config field is real and correct 214 for this project. 2158. **Run relevant checks.** At minimum, run the narrowest tests, 216 lint, type checks, or build steps that validate the change. If 217 you cannot run them, say exactly what remains unverified. 2189. **Self-review the diff.** Remove unrelated edits, debug code, 219 commented-out code, duplication, dead branches, and speculative 220 changes. 22110. **Report only what is true.** Summarize actual code changes and 222 actual verification. Do not imply tests ran if they did not. 223 224## Self-review checklist 225 226Before you finish, check: 227 228- [ ] Did I read the relevant code and follow local patterns? 229- [ ] Did I change only what the request required? 230- [ ] Did I reuse existing logic where appropriate? 231- [ ] Did I verify every unfamiliar dependency, API, and config 232 field? 233- [ ] Did I preserve important contracts and caller expectations? 234- [ ] Did I think through edge cases and failure paths? 235- [ ] Did I avoid speculative abstractions and unrelated cleanup? 236- [ ] Did I run the relevant checks, or clearly say what I could 237 not verify? 238- [ ] Does my summary match the actual diff exactly? 239 240## Anti-patterns to avoid 241 242- **The Hallucinated Dependency.** Adding a package, API, or tool 243 without verifying that it exists and is appropriate. 244- **The Shotgun Edit.** Touching many files or concerns for a 245 small request. 246- **The Duplicate.** Reimplementing logic that already exists in 247 the repo. 248- **The Spec Drift.** Solving a nearby problem instead of the one 249 the user asked for. 250- **The Context Drop.** Ignoring repo-local conventions, helpers, 251 architecture, or deployment constraints. 252- **The Ghost Contract.** Silently changing behavior that callers, 253 data, or integrations depend on. 254- **The Test Dodger.** Deleting, weakening, or skipping tests to 255 make the change appear correct. 256- **The Hidden Dependency.** Writing code that only works because 257 of undeclared setup, implicit state, or missing runtime pieces. 258- **The PR Fiction.** Claiming a change was implemented or 259 verified when the diff and checks do not prove that. 260- **The TODO Patch.** Leaving behind code you cannot explain, 261 incomplete adaptation, or uncertainty disguised as a finished 262 implementation. 263 264## Boundaries 265 266This skill is for implementing and refactoring production code. 267When the task becomes primarily one of these, use the specialized 268skill too: 269 270- **Debugging a failure** → `systematic-debugging` 271- **Writing or reviewing tests** → `testing-practices` 272- **Reviewing an existing diff or PR** → `code-review`