Instructions for Coding Agent

General behaviour

I'm an engineer. I know what I want. You must not propose next actions, unless I ask for that.

Read memory files before creating any plan.
Single sentence questions are not commands, answer and wait for instructions. Do not initiate actions after being asked.

Exploration

You must not use search tools nor commands that scan the whole workstation filesystem, nor significant parts of it.
You can search for directories in sub subdirectory of user's profile directory.
If you want to find a file or directory somewhere else, ask for a permission.

Coding

Prefer using standard library functions or modules.
Avoid creating single use code fragments like functions, methods, etc.
Your built-in knowledge is most likely obsolete for APIs, command syntax and software versions. Check on-line upstream documentation, if in plan mode or asked by the end user at the start of the session.
Do not guess nor infere syntax, API, commands and arguments.
Do not put reasoning comments into the source code.
Source comments always describe the current functions of the code, never document the history.
Unusual coding diverging from upstream documentation can be commented after the end-user approval.

Documentation and code comments

Documentation (README.md, GUIDE.md, docs/*, etc) describes the current state and does not include past state nor things that are missing.
Reasoning and decision explanations go to the ADR.md - architecture decision records file if it has been created by the user.
Change history goes to the CHANGELOG.md, if it has been created by the user.
Do not place documentation like content into comments.
Use heredocs to describe code fragments like functions, classes or methods.
Use terse single sentence comments to describe code paths and purpose of parts of the long functions or code blocks.

Translation

You will ocassionally be asked to translate a program from one language to another, or one framework to a different one. Follow the rules below:

Never translate directly, always apply language established conventions and patterns.
Assess target established convention. Ask if it does not exist.

Terraform

Do not create passthrough output variables, e.g. in an object or modules that take an input, do not expose the exact same value as output.

Markdown style

Do not put --- directly before headers # of any level.
Always separate lists with a blank line from the preceding paragraph.

All created files

Do not use any emojis nor fancy characters (non-ASCII outside of range 0x00 - 0x7f) when creating or modifying content. Do not scan files each time you touch them, just use the right characters.

Git

Never commit on your own without the user's approval.
Never put advertising or attribution information into the commit messages.
Do not include sensitive information in commit messages.
Do not put reasoning or explanations into commit messages.

Running Linux tools

Note: That section applies only to MacOS, ignore it on Linux and Windows.

macOS userland (BSD base64, sed, date, ...) differs from the Linux userland. Never verify Linux behaviour by running it on the Mac - use the local Ubuntu container machine instead.

Check state: container machine list
Run a command: container machine run -n <machine_name> -- <command> [args]
Run a command on the default machine: container machine run -- <command> [args]
Stop it: container machine stop <machine_name>

The -- separator is required when the command takes arguments; without it the call fails with Operation not supported by device. A stopped machine is started automatically by run. The current working directory is available inside the machine, so put throwaway scripts under tmp/ (gitignored) and run them as container machine run -n ubuntu -- bash tmp/check.sh - the scratchpad directory is not visible there.

Verify on Linux whenever a command's behaviour is platform-sensitive, and say which platform any test result came from.

4.0 KiB Raw Permalink Blame History