# Coding

> Best practices for code editing, search, and file operations

- Skill: `nearai/coding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nearai/coding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nearai/coding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nearai (https://skillmd.com/u/nearai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nearai/coding

---


# Coding Best Practices

## Tool Usage Discipline

- **Prefer `apply_patch` over `write_file`** for modifying existing files. It sends only the changed portion, preventing accidental full-file rewrites.
- **Always `read_file` before editing.** Understand the context before changing code. Never edit a file you haven't read.
- **Use `glob` for file discovery** instead of `shell` with `find` or `ls`. It's faster, safer, and returns structured results sorted by modification time.
- **Use `grep` for content search** instead of `shell` with `grep` or `rg`. It provides structured output modes (content, file paths, counts) and pagination.
- **Use `list_dir` for directory exploration** instead of `shell` with `ls`.
- **Read before writing.** Never create or overwrite a file without reading it first (unless it's genuinely a new file).

## Code Change Discipline

- **Minimal changes.** Don't add features, refactor, or "improve" beyond what was asked. A bug fix doesn't need surrounding code cleaned up.
- **No unnecessary comments or docstrings.** Only add comments where the logic isn't self-evident. Don't add type annotations or docstrings to code you didn't change.
- **One thing at a time.** Make focused changes, verify with `read_file`, then move to the next change.
- **Fix the pattern, not just the instance.** When you find a bug, use `grep` to search for all occurrences of the same pattern before committing a fix.

## Code Quality

- Don't introduce security vulnerabilities (command injection, XSS, SQL injection, path traversal).
- Preserve existing code style and conventions. Match the indentation, naming, and patterns of surrounding code.
- Test after changes when test infrastructure exists. Use `shell` to run the project's test command.
- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees.

## Verify Before You Finish

A fix is not done when the code looks right — it is done when you have watched it work and watched everything around it keep working.

- **Reproduce first.** Before changing code, reproduce the reported problem (a failing test, a minimal script, a command) and confirm it fails the way the issue describes. If you can't reproduce it, say so instead of fixing blind.
- **Re-run the reproduction after the fix** and confirm the behavior actually changed.
- **Run the existing tests for every file you modified** — the sibling/module test suite, not just your reproduction. Fixes that hardcode the new behavior often break the old one (e.g. forcing a flag unconditionally when the correct fix is conditional on context).
- **A test you broke is your bug.** If a previously-passing test fails after your change, the fix is wrong or too broad — narrow it until both the new and old behavior pass. Never rationalize a newly-failing test as "unrelated" without proving it fails before your change too.
- **Re-read the final diff before finishing.** Every hunk must be necessary for the fix; revert stray edits, leftover debug output, and drive-by "improvements". Delete any reproduction scripts you created outside the repo's test layout.