154 lines
9.0 KiB
Markdown
154 lines
9.0 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.
|
|
|
|
## 🚦 STATE MACHINE RULES (THINK BEFORE ACT)
|
|
|
|
To prevent premature execution and ensure you follow instructions mechanically, you are operating as a State Machine.
|
|
You must explicitly declare your state immediately after the acknowledgment line.
|
|
|
|
**Valid States:**
|
|
- `STATE: PLAN` (Default state for analysis and planning)
|
|
- `STATE: IMPLEMENTATION` (Only when user explicitly tells you "Approve", "Implement this", or "Go ahead")
|
|
|
|
**Rules for `<STATE: PLAN>`:**
|
|
- **FIRST ACTION REQUIRED:** You MUST ensure `instructions/behavior/core-principles.instructions.md` is loaded into your context before analyzing.
|
|
- **FORBIDDEN:** You CANNOT use `replace_string_in_file`, `create_file`, or run terminal commands that modify state (e.g., `git add`, writing to files). Read-only tools ONLY.
|
|
- **ALLOWED:** You may use `read_file`, `file_search`, `grep_search`, `run_in_terminal` (for read-only commands like `ls`, `cat`), and propose plans.
|
|
- If the user asks for a feature, you MUST propose the implementation strategy first, output a prompt asking for approval, AND STOP.
|
|
- Do NOT output concrete implementation code blocks in your proposals. Propose the strategy in bullet points only.
|
|
|
|
**Rules for `<STATE: IMPLEMENTATION>`:**
|
|
- **CRITICAL PRE-EXECUTION ACTION:** Before executing ANY file edits, you MUST mechanically use the `read_file` tool to *reload* all relevant specific skill files (e.g., `skills/clean-code.instructions.md`, `skills/helm.instructions.md`) for the task. Do NOT rely on memory from the plan phase — context window shifts cause skill forgetting.
|
|
- **ACTIVE SKILL ECHO (MEMORY FORCING FUNCTION):** Immediately after reading the skill files, and BEFORE generating any code blocks or edits, you MUST output a section `### Active Skills:` summarizing the 2-3 most critical, restrictive rules you just read. Writing them out physically forces them into your immediate attention window.
|
|
- **ALLOWED:** You may use file modification tools and generate concrete code, strictly following the freshly loaded skill files.
|
|
- **RETURN TO PLAN:** Once your execution steps for the current prompt are finished, your VERY NEXT response MUST transition back to `STATE: PLAN`. You are FORBIDDEN from remaining in `IMPLEMENTATION` state indefinitely.
|
|
|
|
---
|
|
|
|
## 🚫 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
|
|
- [Grill Me](instructions/skills/grill-me.instructions.md) - Active workflow: relentlessly interview user about a design/plan. ONE question at a time. No code.
|
|
- [Use Cases](instructions/skills/use-cases.instructions.md) - Active workflow: strictly formatted, concise business use cases to prevent bloat.
|
|
- [Write Skill](instructions/skills/write-skill.instructions.md) - Meta-skill: interview user to create a new, high-quality AI instruction/skill file.
|
|
|
|
- [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 to "grill me" / test plan → instructions/skills/grill-me.instructions.md
|
|
User asks for use cases or reqs → instructions/skills/use-cases.instructions.md
|
|
User wants to create a new AI skill → instructions/skills/write-skill.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
|