hoko-agent-guidelines

HOKO Corp — AI Agent Coding Guidelines

HOKO Corp's standard behavioral guidelines to reduce common LLM coding mistakes.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

Scope: how much logic and abstraction you write - not how it's split across files.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

5. Small Files, Single Purpose

Split code across small, single-purpose files. Agents read and edit small files more reliably than large ones.

Scope: file and module layout - not how much code you write.

• One function, component, or module per file - where it doesn't hurt readability.
• Split a file once it grows past one clear responsibility.
• Large files bloat agent context and produce bigger, riskier diffs.
• A recommendation to improve quality, not a hard line limit.

6. Reuse APIs Before Creating

Check for an existing API before adding one. Extend or reuse before you build new.

• Search for an existing endpoint that already does the job.
• If a similar API exists, extend or reuse it instead of duplicating.
• Create a new API only when nothing existing can reasonably be extended.
• Define HTTP APIs with an OpenAPI spec where possible - a single source of truth for clients and docs.

7. Guard Secrets

Never expose credentials. Don't read secret stores unless the task requires it.

• Never print API keys, tokens, passwords, or secret values in output.
• Don't read credential files (.env, ~/.claude/.credentials.json, key files) unless the task explicitly needs them.
• Don't run env / printenv to fish for secrets; don't commit secrets or paste them into code.
• When you must reference a secret, use its name or a placeholder, not its value.

8. Finish What You Start

No placeholders, no skeletons, no silent TODOs. Complete the work in scope - or flag what's left out loud.

Scope: completeness of what you were asked to build - not adding work beyond it (that's Principle #2).

• No stub functions, fake return values, or TODO/FIXME left where real logic belongs.
• Don't mark something "acceptable for now" or "good enough for Phase X" - placeholders look done, get forgotten, and ship.
• A skeleton that returns hardcoded or empty data is more dangerous than an honest error - it hides the gap instead of surfacing it.
• If a piece genuinely can't be finished now, don't bury it in a comment. Say so explicitly and track it where it won't be missed.