Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (70 loc) · 5 KB

AGENTS.md

File metadata and controls

86 lines (70 loc) · 5 KB
Raw

Development instructions

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.
  • Use thinking methods like Elon Musk's first principle reasoning or design-thinking for complex tasks.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

  • 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.
  • Don't repeat yourself.

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.
  • 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. Code quality and style

  • Write high-quality, developer-friendly and clean-code, use design-patterns (Refactoring Guru) where helpful.
  • Include docstrings and comments to explain the why of a non-obvious method or code. No decorative comments.
  • Write memory and compute efficient code.
  • Write pythonic code and use builtins when it simplifies (generators, list-comprehensions, functools).
  • Reduce complexity and boilerplate. Remove unused code.
  • State unclear variable names and rename for better readability and clearity.
  • Avoid local imports
  • Do not write "deprecated" or backward compability code.
  • Update the README.md if there's user related important changes. Update TECHNICAL_README.md for architectural, or project maintainer important changes. Keep the .md update brief use technical correct terms.
  • Write ruff formatted code with ignores E203, W501, W293, W291 and lineLenght 120.
  • Avoid using direct cmd python calls and pip installs.
  • When executing python code, always use the local venv of the corresponding project.
  • Dev tools are make, ruff, mypy, pytest.
  • Always ask before writing a test file.

5. Reason and thinking style

Do thinking and reasoning like a smart caveman.

  • Cut all filler, keep technical substance.
  • Drop articles (a, an, the), filler (just, really, basically, actually).
  • Drop pleasantries (sure, certainly, happy to).
  • No hedging. Fragments fine. Short synonyms.
  • Technical terms stay exact. Code blocks unchanged.
  • Pattern: [thing] [action] [reason]. [next step]

6. Public facing texts: Readmes, prints, logs.

  • Write as technically brilliant European expert who gives you straight answers, backs claims with data, and genuinely wants you to succeed.
  • Ttone spectrum Formality 35% (lean casual) · Humor 25% (dry, never flippant) · Complexity 40% (lean technical) · Confidence 80% (very confident).
  • Direct without being cold. Say what you mean, no corporate padding. Warm without being informal. Complete sentences, measured enthusiasm. Committed, not hedging.
  • Committed, not hedging. "This works", not "this might work".
  • "We" for the platform, "you" for the reader. Reserve "I" for rare authored guides only.
  • Developer-first, technical correct terms.
  • No em-dashes. The character — (U+2014) must not appear in ANYWHERE. Use a period, comma, parentheses, or colon.
  • No marketing adverbs like seamlessly, effortlessly, robust, powerful, cutting-edge, automatically, intelligently, revolutionary, game-changing, world-class, best-in-class. E.g. three steps, ~X minutes" beats "easy onboarding".
  • No bullet-everything. Bullets only for true enumerations (statuses, regions, tiers).
  • Subtle transmit socaity's vision and use emotional-intelligence and marketing techniques for end-user intent based messages.
  • Use google docstring format.
  • The four brand hues (each tied to an ICP) with Tonal scales (50/300/500/700/900). Apply where makes sense. | Name | Hex | Meaning / ICP | | ---------------------------- | ----------- | ------------------------------------------------------------------------- | | Neon Green | #5A8F00 | Developer. Active system health, engineering precision, technical truth. | | Silicon Blue | #0A86BF | SMB CTO. Enterprise stability, secure infrastructure, professional trust. | | Creator Violet | #7C3AED | Creator. Generative potential, creative momentum, warmth. | | Signal Pink (Rose) | #EC4899 | Alert. Warnings, critical status, high-priority attention. |