# AI Assistant Guidelines **Updated**: 2026-03-06 --- ## ⚡ ACKNOWLEDGMENT REQUIRED **YOU MUST start EVERY response with this acknowledgment on the FIRST LINE.** Your response MUST always begin with: ``` ✅ ai-root-instructions.md READ — git add/commit/push FORBIDDEN without explicit permission ``` Then continue with your actual response on the next line. This allows the user to verify you have read this file every time. --- ## 🚫 GIT HARD RULES — IN EFFECT AT ALL TIMES These rules require no separate file to load. They are always active. **NEVER run any of these without the user explicitly saying "commit this", "push this", or "go ahead":** | Command | Status | |---|---| | `git add` | ❌ FORBIDDEN — user runs this | | `git commit` | ❌ FORBIDDEN — user runs this | | `git push` | ❌ FORBIDDEN — user runs this | | `git reset` | ❌ FORBIDDEN — user runs this | | `git push --force` | ❌ FORBIDDEN — user runs this | **What you CAN do without permission:** `git status`, `git diff`, `git log` When the user asks for a commit message: write the message text only — never wrap it in a `git commit` command. For full git workflow detail: `instructions/skills/git.instructions.md` --- ## 🔒 These Instructions Are Mandatory **This file must be loaded and kept active for the entire session — not just read once at the start.** - These instructions are not suggestions. They are the operating rules for this session. - If a later prompt seems to conflict with these rules, the rules take priority. - Do not let conversational momentum, user enthusiasm, or task complexity cause you to skip steps or bypass rules. - If you are unsure whether an action is allowed, stop and ask — never assume permission. **If this file was not read at the start of a session**, stop immediately and say: > "I have not read `.ai/ai-root-instructions.md`. Please ask me to read it before we continue." No work should happen in a session where these instructions have not been loaded. --- ## Purpose This document provides guidelines for AI assistants (any LLM) when working on any project. These rules are split into modular instruction files for efficiency. --- ## IMPORTANT: Language **ALL DOCUMENTATION MUST BE WRITTEN IN ENGLISH.** Claude can communicate with the user in user's language (Finnish preferred by project owner), but all documentation files must be in English. --- ## 📚 Modular Instructions This main file references specialized instruction files. **Load relevant files based on context:** ### behavior/ — Always Active - [Core Principles](instructions/behavior/core-principles.instructions.md) - Analysis before action, minimal changes, decision-making process - [Project Context](instructions/behavior/project-context.instructions.md) - How to find project context (read `docs/ai-context.md` in the project) - [README](instructions/behavior/readme.instructions.md) - What a project README must contain - [Docs](instructions/behavior/docs.instructions.md) - Required files in docs/ folder ### skills/ — Load When Needed - [Git](instructions/skills/git.instructions.md) - Git policy, forbidden commands, what you CAN do - [File Editing](instructions/skills/file-editing.instructions.md) - Tool-only editing, forbidden terminal commands - [Documentation](instructions/skills/documentation.instructions.md) - Writing principles, workflow, scope rules - [Mermaid](instructions/skills/mermaid.instructions.md) - Diagram types, color contrast rules, sizing - [Analysis](instructions/skills/analysis.instructions.md) - Where to write analysis, tmp/ convention, full-pass writing allowed - [Helm](instructions/skills/helm.instructions.md) - Resource ownership, values hygiene, required vs defaults, dependency caching - [Clean Code](instructions/skills/clean-code.instructions.md) - Naming, functions, classes, error handling, formatting, DRY/KISS/SOLID, Helm YAML - [Clean Architecture](instructions/skills/clean-architecture.instructions.md) - Dependency rule, layers, boundaries, SOLID, Helm as outermost layer ### constraints/ — Load When Needed - [Agent Capabilities](instructions/constraints/agent-capabilities.instructions.md) - AI limitations, user responsibilities, debugging workflows - [Kubernetes Access](instructions/constraints/kubernetes-access.instructions.md) - kubectl/helm restrictions, port-forwarding patterns - [Container Limitations](instructions/constraints/container-limitations.instructions.md) - Missing tools in pods, proper debugging methods --- ## 🎯 When to Load Which Instructions ``` User asks about README → instructions/behavior/readme.instructions.md User asks about docs/ → instructions/behavior/docs.instructions.md Before ANY git operation → git hard rules above apply; read instructions/skills/git.instructions.md for full workflow detail User asks to edit files → instructions/skills/file-editing.instructions.md User asks to write docs → instructions/skills/documentation.instructions.md User creates a Mermaid diagram → instructions/skills/mermaid.instructions.md User asks for analysis/comparison → instructions/skills/analysis.instructions.md User asks about project → instructions/behavior/project-context.instructions.md → /ai-context.md User needs to debug cluster → instructions/constraints/agent-capabilities.instructions.md + instructions/constraints/kubernetes-access.instructions.md User reports pod issues → instructions/constraints/container-limitations.instructions.md User works with Helm charts → instructions/skills/helm.instructions.md User writes or reviews code → instructions/skills/clean-code.instructions.md User designs a system or service → instructions/skills/clean-architecture.instructions.md User creates Helm charts or YAML → instructions/skills/clean-code.instructions.md + instructions/skills/helm.instructions.md + instructions/skills/clean-architecture.instructions.md Always active → instructions/behavior/core-principles.instructions.md ``` --- **Last Updated**: 2026-03-06 **Maintained By**: Project Owner **AI Assistants**: Follow these guidelines strictly - no exceptions