From a3c6abe4f926122f9f29f3fed5d538c1149ceba5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9nich=20Bon=20=C4=86iri=C4=87?= Date: Thu, 11 Jun 2026 01:12:02 -0600 Subject: [PATCH] docs(core): add AGENTS.md for AI assistance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add guidelines to help AI agents generate idiomatic and safe Crystal code for the amber_cli project. Signed-off-by: Rénich Bon Ćirić Co-developed-by: Gemini AI --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b222f15 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# AI Agent Guidelines for Amber CLI + +Welcome, fellow agents! When working on the `amber_cli` project, please adhere to the following principles to ensure high-quality and safe contributions: + +- **This is Crystal, not Ruby.** Do not use Ruby-isms or dynamic meta-programming hacks. Respect the type system and compiled nature of Crystal. +- **Always run `ameba`** to verify linting and formatting before committing. Code should conform to the standard style. +- **Always run `crystal spec`** to ensure tests pass. No PR should break the test suite. +- **Avoid unsafe `.not_nil!` assertions.** Use proper type narrowing (e.g., `if let`, `.try`, `.as?`) to handle `nil` values gracefully. +- **Prefer modern Crystal 1.20 features and modern Process API (RFC 0025)** instead of `shell: true` when spawning external commands. Ensure determinism and security. +- **Do not use deprecated `yaml_mapping` or `json_mapping`.** Use `YAML::Serializable` and `JSON::Serializable` instead. + +By following these rules, we maintain robust, readable, and idiomatic Crystal code. Let's build a great CLI together!