99 lines
4.9 KiB
Markdown
99 lines
4.9 KiB
Markdown
# Instructions for Coding Agent
|
|
|
|
## General behaviour
|
|
|
|
- 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.
|
|
- Comments pointing to a bug or misunderstood action must be considered as requests to analyze the problem and provide a solution or options, and are not a call to make a change.
|
|
|
|
## 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 `src` subdirectory of user's profile directory.
|
|
- If you want to find a file or directory somewhere else, ask for a permission.
|
|
|
|
## General editing
|
|
|
|
- Use available edit tools like Read, ReadFile, Edit, EditFile, Write, WriteFile, etc.
|
|
- Bulk edits must always be justified and then approved by the user before execution. Use Perl for bulk edits, unless instructed otherwise.
|
|
|
|
## Running command line utilities
|
|
|
|
- Avoid creating single line multiple command invocations. These constructs make it harder to configure allowed commands for the session.
|
|
|
|
## Coding
|
|
|
|
- Prefer using standard library functions or modules in standalone scripts or utilites.
|
|
- 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.
|
|
- Design decision go to ADR.md (Architectural Decision Record).
|
|
|
|
### 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 related to the current state of the codebase/repository - go to the ADR.md. ADR is not for documenting history of the decisions.
|
|
- Change history goes to the CHANGELOG.md.
|
|
- 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, unless the output is used as an input to a report or will be passed to another tool or module.
|
|
|
|
## 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.
|
|
|
|
## Container runtime
|
|
|
|
You may have container runtime available on the host machine, however you
|
|
must obtain the user's approval before using it. The rule applies to any container runtime,
|
|
including Docker, Podman, LXC, Apple container CLI, etc.
|
|
|
|
### 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.
|