Oscar's CLAUDE.md for agentic coding. Feedback welcomed!

oh-CLAUDE.md

Last updated: 10 Feb 2026

Guidelines

For Bash

IMPORTANT: Avoid commands that cause output buffering issues

• DO NOT pipe output through head, tail, less, or more when monitoring or checking command output
• DO NOT use | head -n X or | tail -n X to truncate output - these cause buffering problems
• Instead, let commands complete fully, or use --max-lines flags if the command supports them
• For log monitoring, prefer reading files directly rather than piping through filters

When checking command output:

• Run commands directly without pipes when possible
• If you need to limit output, use command-specific flags (e.g., git log -n 10 instead of git log | head -10)
• Avoid chained pipes that can cause output to buffer indefinitely

Documentation look-up

When building with external libraries / APIs, always use Context7 to look up the latest documentation without me having to explicitly ask or invoke context7.

JavaScript/TypeScript Package Management

Default to using Bun as the JavaScript, TypeScript & JSX toolkit. Fall back to npm only if package-lock.json already exists in the project.

Detection:

• bun.lockb or no lockfile → use bun
• package-lock.json → use npm
• Never mix package managers

Bun Commands (Default):

• Install: bun install / bun add <pkg> / bun add -d <pkg>
• Run scripts: bun run <script> or bun <file>.ts
• npx equivalent: bunx <pkg>

npm Fallback:

• Install: npm install / npm install <pkg> / npm install -D <pkg>
• Run scripts: npm run <script>

For Python

Follow the Python Developer Tooling Handbook's recommendations:

• Reference: https://pydevtools.com/handbook/explanation/modern-python-project-setup-guide-for-ai-assistants.md
• For more information: https://pydevtools.com/llms.txt

Use uv exclusively for Python package management: https://docs.astral.sh/uv/ All Python dependencies must be installed, synchronized, and locked using uv

Never use pip, pip-tools, poetry, or conda directly for dependency management.

Use these commands:

• Install dependencies: uv add <package>
• Remove dependencies: uv remove <package>
• Sync dependencies: uv sync

Running Python code:

• Run a Python script with uv run <script-name>.py
• Run Python tools like Pytest with uv run pytest or uv run ruff
• Launch a Python repl with uv run python

Manage scripts with PEP 723 inline metadata:

• Run a Python script with inline metadata (dependencies defined at the top of the file) with: uv run script.py
• You can add or remove dependencies manually from the dependencies = section at the top of the script, or
• Or using uv CLI:
  • uv add package-name --script script.py
  • uv remove package-name --script script.py

git, commits, pull requests

• Your primary method for interacting with GitHub should be the GitHub CLI.
• In all interactions and commit messages, be descriptive, but extremely concise.
• When tagging Claude in GitHub issues, use '@claude'
• When creating branches, prefix them with oh- to indicate they came from me (“Oscar Hong”).

Changesets

To add a changeset, write a new file to the .changeset directory.

The file should be named 0000-your-change.md. Decide yourself whether to make it a patch, minor, or major change.

The format of the file should be:

---
"evalite": patch
---

Description of the change.

The description of the change should be user-facing, describing which features were added or bugs were fixed.

Planning

At the end of each plan, give me a list of unresolved questions to answer or points of clarification needed, if any. Make the questions extremely concise.

When exiting plan mode, assess whether the solution is over-engineered, under-engineered, or appropriately scoped. State which and why in one sentence.

Bug Fixes

For production bugs: write a failing test that reproduces the bug BEFORE writing the fix.

Abide by “ohong Engineering Philosophy”

1. Rule of Modularity — Claude should build programs out of simple parts connected by well-defined interfaces, so problems are local and parts can be replaced to support new features. Break down projects into small, straightforward cooperating pieces rather than overly complex monolithic programs. This discourages over-engineering, which in reality produces bug-prone code.
2. Rule of Clarity — Claude should write programs as if the most important communication is to the developer, including itself, who will read and maintain the program. When faced with the choice, make data more complicated rather than procedural logic, because it is easier for humans to understand complex data compared with complex logic.
3. Rule of Separation — Claude should separate the mechanisms of programs from the policies of programs, so policies can be changed without destabilising mechanisms. For example, abstracting API or model providers to env variables so they can be easily swapped out with a one-line change.
4. Rule of Robustness — Claude should design programs that fail in a manner that is easy to localise and diagnose — in other words, "fail noisily." Code that is easy to understand is easier to stress test for unexpected conditions. Incorrect output must not silently become input and corrupt other code undetected.
5. Rule of Least Surprise — Claude should design programs that build on top of users' expected knowledge; for example, '+' should always mean addition in a calculator program. Build intuitive products that can be used without consulting manuals, tooltips, or heavy-handed onboarding.
6. Rule of Silence — Claude should design programs so that they do not print unnecessary output, allowing other programs and developers to pick out the information they need without parsing verbosity.
7. Rule of Optimisation — Claude should prototype software before polishing it, to prevent spending too much time for marginal gains.