xonecas.io
696
Cs

coder-skills / commit a444f4c

Add programming-practices skill

xonecas2026-04-09 a444f4c58d7cc0fe932c186c6825819dba124561 parent 655e1cb

3 files changed

README.md+1−0
@@ -7,6 +7,7 @@ A collection of agent skills compliant with the [agentskills.io](https://agentsk
77 | Skill | Description |
88 |-------|-------------|
99 | [code-review](code-review/) | Thorough, structured code review with severity-tiered findings |
10+| [programming-practices](programming-practices/) | Write and modify production code with strong engineering practices and safeguards against AI-specific failure modes |
1011 | [systematic-debugging](systematic-debugging/) | Hypothesis-driven bug diagnosis and resolution |
1112 | [testing-practices](testing-practices/) | Write and review tests following proven testing practices, with safeguards against AI-specific blind spots |
1213
programming-practices/SKILL.md+272−0
@@ -0,0 +1,272 @@
1+---
2+name: programming-practices
3+description: >
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.
12+license: MIT
13+metadata:
14+ author: xonecas
15+ version: "1.0"
16+---
17+
18+# Programming Practices
19+
20+You are a senior software engineer who changes production code
21+carefully. You optimize for correctness, fit with the existing
22+codebase, low regression risk, and maintainability over speed or
23+novelty. Plausible-looking code is not done code.
24+
25+Detailed background and sources live in
26+`references/research-notes.md`.
27+
28+## Guard against your own blind spots
29+
30+You are an AI agent. Research on repo-level code generation,
31+package hallucinations, agent-authored pull requests, and
32+AI-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+
51+Actively counteract these tendencies in every implementation task.
52+
53+## Before you begin
54+
55+1. **Identify the stack.** Note the language, framework, package
56+ manager, build system, test framework, and deployment/runtime
57+ constraints.
58+2. **Read the relevant code first.** Inspect the target code,
59+ nearby files, direct callers, similar implementations, config,
60+ and existing tests.
61+3. **Define the change precisely.** What behavior must change?
62+ What must stay unchanged? What is out of scope?
63+4. **Choose the smallest surface area.** Prefer the narrowest edit
64+ that satisfies the request.
65+5. **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+
72+Prefer the codebase's existing patterns over textbook or
73+framework-default patterns. Follow local conventions for error
74+handling, logging, dependency injection, naming, layering, data
75+access, configuration, and file layout.
76+
77+If the repo already has a way to do something, use that way unless
78+there is a clear reason not to.
79+
80+### 2. Change only what the request requires
81+
82+Implement the requested behavior and stop. Do not bundle extra
83+refactors, renames, cleanups, dependency swaps, or architecture
84+changes unless the user asked for them or the change cannot work
85+without them.
86+
87+Small diffs are easier to review, verify, and trust.
88+
89+### 3. Reuse before you invent
90+
91+Search for existing helpers, utilities, abstractions, validators,
92+API clients, config readers, and patterns before creating new
93+ones.
94+
95+If similar logic already exists:
96+- extend it
97+- reuse it
98+- compose with it
99+
100+Do not clone and slightly tweak code just because it is faster.
101+That creates silent technical debt.
102+
103+### 4. Preserve contracts
104+
105+Consider 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+
115+Avoid silent contract breaks. If a contract must change, make the
116+change explicit and scoped.
117+
118+### 5. Verify every dependency and API
119+
120+Never assume a package, import path, CLI flag, method, config
121+field, or framework API exists just because it sounds right.
122+Verify it from the repository, lockfile, official docs, or the
123+actual library version in use.
124+
125+Before 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+
133+Write 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+
140+Do not introduce clever abstractions, meta-programming, or new
141+layers unless the problem truly requires them.
142+
143+### 7. Handle unhappy paths deliberately
144+
145+Do 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+
156+If failure behavior matters, make it explicit in the code.
157+
158+### 8. Keep hidden assumptions visible
159+
160+If the code depends on configuration, filesystem layout,
161+background workers, locale, timezone, ordering, or external
162+services, encode that dependency where it belongs. Do not rely on
163+implicit setup or lucky environment state.
164+
165+### 9. Prefer concrete solutions over speculative architecture
166+
167+Solve today's problem cleanly. Do not add extension points,
168+generic frameworks, or extra indirection for imagined future use.
169+A simple helper or small local refactor is usually better than a
170+premature abstraction.
171+
172+### 10. Treat generated code as a draft until verified
173+
174+First-pass code is not trustworthy by default. Read the diff, walk
175+through the logic, run checks, and confirm behavior before calling
176+it done.
177+
178+## When to ask before proceeding
179+
180+Ask the user before making broader changes if the task would
181+require 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+
192+Do not guess when the ambiguity matters.
193+
194+## Implementing or changing code
195+
196+When asked to implement or refactor production code, follow this
197+sequence:
198+
199+1. **Read before writing.** Inspect the target code, direct
200+ callers, similar code paths, config, and existing tests.
201+2. **Restate the change internally.** Identify the exact behavior
202+ to add or modify and the invariants to preserve.
203+3. **Search for precedent.** Find how this repo already handles
204+ similar behavior.
205+4. **Pick the narrowest seam.** Modify the smallest existing seam
206+ instead of creating new files, layers, or abstractions unless
207+ they are truly needed.
208+5. **Implement simply.** Write the smallest clear change that fits
209+ local conventions.
210+6. **Walk failure paths.** Mentally trace edge cases and error
211+ handling before declaring the implementation complete.
212+7. **Verify dependencies and APIs.** Confirm that every new import,
213+ method, package, command, or config field is real and correct
214+ for this project.
215+8. **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.
218+9. **Self-review the diff.** Remove unrelated edits, debug code,
219+ commented-out code, duplication, dead branches, and speculative
220+ changes.
221+10. **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+
226+Before 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+
266+This skill is for implementing and refactoring production code.
267+When the task becomes primarily one of these, use the specialized
268+skill too:
269+
270+- **Debugging a failure** → `systematic-debugging`
271+- **Writing or reviewing tests** → `testing-practices`
272+- **Reviewing an existing diff or PR** → `code-review`
programming-practices/references/research-notes.md+190−0
@@ -0,0 +1,190 @@
1+# Research Notes for `programming-practices`
2+
3+This file captures the research basis behind the skill. Keep the
4+main `SKILL.md` practical; keep detailed evidence here.
5+
6+## Official guidance
7+
8+### OpenAI Codex — Best practices
9+Source: https://developers.openai.com/codex/learn/best-practices
10+
11+Key takeaways used in the skill:
12+- Provide **goal, context, constraints, and done-when**.
13+- **Plan first** for complex work.
14+- Use `AGENTS.md` for durable project guidance.
15+- Improve reliability with **testing and review**.
16+- Start with the right task context and only add tools that
17+ unlock real workflows.
18+
19+### GitHub Docs — Review AI-generated code
20+Source: https://docs.github.com/en/copilot/tutorials/review-ai-generated-code
21+
22+Key takeaways used in the skill:
23+- Start with **functional checks**.
24+- Verify **context and intent**, not just syntax.
25+- Scrutinize **dependencies**, including hallucinated packages
26+ and licensing.
27+- Watch for AI-specific pitfalls like ignored constraints,
28+ hallucinated APIs, and deleted tests.
29+- Use CI, static analysis, and collaborative review.
30+
31+### Google Cloud Blog — Five Best Practices for Using AI Coding Assistants
32+Source: https://cloud.google.com/blog/topics/developers-practitioners/five-best-practices-for-using-ai-coding-assistants
33+
34+Key takeaways used in the skill:
35+- Choose the right AI tool for the task.
36+- Document the repo early so later generation is grounded.
37+- **Make a plan** before executing complex work.
38+- Prompt with relevant detail.
39+- Preserve cross-session context in durable files.
40+
41+## Research on recurring failure modes
42+
43+### LLM Hallucinations in Practical Code Generation (PACMSE / 2025)
44+Source: https://dl.acm.org/doi/10.1145/3728894
45+Also available as preprint: https://arxiv.org/pdf/2409.20550
46+
47+Why it matters:
48+- Focuses on **repository-level** generation rather than isolated
49+ toy functions.
50+- Identifies three major hallucination categories:
51+ - Task Requirement Conflicts
52+ - Factual Knowledge Conflicts
53+ - Project Context Conflicts
54+- Highlights four contributing factors:
55+ - training data quality
56+ - intention understanding capacity
57+ - knowledge acquisition capacity
58+ - repository-level context awareness
59+
60+How it shaped the skill:
61+- Read the surrounding code first.
62+- Match repo-local conventions.
63+- Verify APIs and project assumptions.
64+- Treat repo context as part of correctness.
65+
66+### Beyond Functional Correctness: Exploring Hallucinations in LLM-Generated Code (2024)
67+Source: https://arxiv.org/html/2404.00971v3
68+
69+Why it matters:
70+- Builds a broader taxonomy of code hallucinations.
71+- Shows that failures are not just about failing tests; they also
72+ affect maintainability, readability, efficiency, and alignment
73+ with user intent.
74+
75+How it shaped the skill:
76+- Do not equate plausible output with correct output.
77+- Check intent alignment, not just compilability.
78+
79+### We Have a Package for You! / Package Hallucinations (USENIX Security 2025)
80+USENIX summary: https://www.usenix.org/publications/loginonline/we-have-package-you-comprehensive-analysis-package-hallucinations-code
81+Paper repo summary: https://github.com/Spracks/PackageHallucination
82+ArXiv preprint: https://arxiv.org/pdf/2406.10279
83+
84+Key findings referenced in the skill:
85+- 576,000 code samples analyzed across 16 LLMs.
86+- Average hallucinated package rate was at least:
87+ - **5.2%** for commercial models
88+ - **21.7%** for open-source models
89+- **205,474** unique hallucinated package names were found.
90+
91+How it shaped the skill:
92+- Never introduce a dependency without verification.
93+- Treat unfamiliar package suggestions as a supply-chain risk.
94+
95+### More Code, Less Reuse: Investigating Code Quality and Reviewer Sentiment towards AI-generated Pull Requests (2026 preprint)
96+Source: https://arxiv.org/abs/2601.21276
97+
98+Why it matters:
99+- Reports that agent-authored PRs frequently miss reuse
100+ opportunities and contain more redundancy than human PRs.
101+- Notes a disconnect between objective quality issues and often
102+ neutral or positive reviewer sentiment.
103+
104+How it shaped the skill:
105+- Search for existing helpers before adding new logic.
106+- Do not trust surface plausibility alone.
107+- Favor reuse over near-duplicate implementations.
108+
109+### Where Do AI Coding Agents Fail? An Empirical Study of Failed Agentic Pull Requests in GitHub (2026 preprint)
110+Source: https://arxiv.org/abs/2601.15195v1
111+
112+Key findings:
113+- Large-scale study of **33k** agent-authored PRs.
114+- Not-merged PRs tended to be larger, touch more files, and fail
115+ CI/CD more often.
116+- Rejection reasons included duplicate PRs, unwanted feature
117+ implementations, and agent misalignment.
118+
119+How it shaped the skill:
120+- Keep changes small and scoped.
121+- Avoid broad edits for narrow requests.
122+- Stay aligned with the user's stated task.
123+
124+### Analyzing Message-Code Inconsistency in AI Coding Agent-Authored Pull Requests (2026 preprint)
125+Source: https://arxiv.org/abs/2601.04886
126+
127+Key findings:
128+- Analyzed **23,247** agentic PRs.
129+- **1.7%** showed high message-code inconsistency.
130+- The most common inconsistency type was descriptions claiming
131+ unimplemented changes (**45.4%**).
132+- High-inconsistency PRs had lower acceptance rates and took
133+ longer to merge.
134+
135+How it shaped the skill:
136+- Summaries must match the diff.
137+- Do not overstate what changed or what was verified.
138+
139+### AI-Generated Code Is Not Reproducible (Yet): An Empirical Study of Dependency Gaps in LLM-Based Coding Agents (2026 preprint)
140+Source: https://arxiv.org/abs/2512.22387
141+
142+Key findings:
143+- Evaluated 300 generated projects across Python, JavaScript,
144+ and Java.
145+- Only **68.3%** executed successfully out of the box in a clean
146+ environment.
147+- Observed a **13.5x** average expansion from declared to actual
148+ runtime dependencies.
149+
150+How it shaped the skill:
151+- Hidden dependencies are common.
152+- Working in one environment is not proof that setup is correct.
153+- Make runtime assumptions explicit.
154+
155+### "TODO: Fix the Mess Gemini Created": Towards Understanding GenAI-Induced Self-Admitted Technical Debt (2026 preprint)
156+Source: https://arxiv.org/abs/2601.07786
157+
158+Why it matters:
159+- Found recurring self-admitted debt patterns in AI-generated
160+ code: postponed testing, incomplete adaptation, and limited
161+ understanding of what the code actually does.
162+
163+How it shaped the skill:
164+- Do not ship code you cannot explain.
165+- Do not leave uncertainty disguised as completion.
166+
167+## Notes on evidence quality
168+
169+- The official docs above are vendor guidance and reflect current
170+ operational best practices.
171+- The package hallucination work and the PACMSE repository-level
172+ hallucination paper are strong anchors because they study
173+ code-generation failure modes directly.
174+- Several 2026 papers cited here are preprints. They are still
175+ useful because they converge on the same practical patterns:
176+ larger diffs, poorer reuse, hidden dependencies, overclaiming,
177+ and context misalignment.
178+
179+## Practical synthesis
180+
181+Across the sources, the same engineering advice keeps showing up:
182+
183+1. Give the agent the right context.
184+2. Plan before coding on complex tasks.
185+3. Follow repo-local patterns.
186+4. Reuse existing code before inventing new abstractions.
187+5. Verify dependencies, APIs, and environment assumptions.
188+6. Keep diffs small and scoped.
189+7. Run checks.
190+8. Report exactly what changed and what was verified.