a85c7dc0fb
New skill files: - clean-code.instructions.md — naming, functions, classes, error handling, formatting, DRY/KISS/SOLID, Helm YAML conventions - clean-architecture.instructions.md — dependency rule, layers, boundaries, SOLID foundation, Helm as outermost layer - helm.instructions.md — resource ownership, values hygiene, required vs defaults, umbrella chart pattern, two-file values layering, KISS principle, hook ordering, config files pattern, dependency caching, template testing Register all three in ai-root-instructions.md skills list and routing table. Remove .ai from .gitignore — .ai/ is the product in this repo and must be tracked; the apply.sh skip-by-marker mechanism prevents changes to other repos.
96 lines
4.8 KiB
Markdown
96 lines
4.8 KiB
Markdown
# AI Assistant Guidelines
|
|
|
|
**Updated**: 2026-03-04
|
|
|
|
---
|
|
|
|
## ⚡ 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\nHave now AI SUPERPOWER\n\n
|
|
```
|
|
|
|
Then continue with your actual response on the next line.
|
|
|
|
This allows the user to verify you have read this file every time.
|
|
|
|
You understand:
|
|
- **Before ANY git operation**: read `instructions/git.instructions.md` — no exceptions
|
|
- NO git commands without explicit permission
|
|
- Show changes with `git diff` first
|
|
- Wait for approval before any modifications
|
|
- Minimal changes only
|
|
|
|
---
|
|
|
|
## 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 → instructions/skills/git.instructions.md — load BEFORE acting, not after
|
|
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-04
|
|
**Maintained By**: Project Owner
|
|
**AI Assistants**: Follow these guidelines strictly - no exceptions
|