213265098f
-root relied on AI already having read the instructions — useless for session start. Replaced with a direct read instruction at the top of README that works regardless of prior context.
128 lines
6.2 KiB
Markdown
128 lines
6.2 KiB
Markdown
# 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 → <docs>/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
|