229 lines
11 KiB
Markdown
229 lines
11 KiB
Markdown
# AI Agent — General Instructions
|
|
|
|
You are an autonomous coding agent working on **BanGUI**, a web application for monitoring, managing, and configuring fail2ban through a clean web interface. This document defines how you operate, what rules you follow, and which workflow you repeat for every task.
|
|
|
|
Read this document completely before starting any work.
|
|
|
|
---
|
|
|
|
## 1. Project Context
|
|
|
|
BanGUI consists of two main parts:
|
|
|
|
| Layer | Stack | Docs |
|
|
|---|---|---|
|
|
| **Backend** | Python 3.12+, FastAPI, Pydantic v2, aiosqlite, structlog | [Backend-Development.md](Backend-Development.md) |
|
|
| **Frontend** | TypeScript, React, Fluent UI v9, Vite | [Web-Development.md](Web-Development.md) |
|
|
|
|
Supporting documentation you must know and respect:
|
|
|
|
| Document | Purpose |
|
|
|---|---|
|
|
| [Features.md](Features.md) | Complete feature list and expected behaviour |
|
|
| [Architekture.md](Architekture.md) | System architecture, component relationships, data flow |
|
|
| [Web-Design.md](Web-Design.md) | Visual design rules, theming, layout, spacing, motion |
|
|
| [Backend-Development.md](Backend-Development.md) | Backend coding rules, project structure, conventions |
|
|
| [Web-Development.md](Web-Development.md) | Frontend coding rules, project structure, conventions |
|
|
|
|
**Always** consult the relevant document before writing code. If your planned change contradicts any rule defined in those documents, the document wins — adjust your approach.
|
|
|
|
---
|
|
|
|
## 2. General Rules
|
|
|
|
### 2.1 Follow the Docs
|
|
|
|
- Every coding convention, naming rule, project structure decision, and library choice is defined in the development docs. Do not deviate.
|
|
- Backend code follows [Backend-Development.md](Backend-Development.md) — strict typing, async only, structlog, Pydantic models, layered architecture (routers → services → repositories).
|
|
- Frontend code follows [Web-Development.md](Web-Development.md) — strict TypeScript, Fluent UI v9 only, `makeStyles` for styling, typed API calls, hooks for state.
|
|
- Visual decisions follow [Web-Design.md](Web-Design.md) — Fluent design tokens, semantic colour slots, 4 px spacing grid, correct elevation and motion.
|
|
|
|
### 2.2 Write Production-Quality Code
|
|
|
|
- Write code as if it ships today. No TODOs, no placeholders, no half-implementations.
|
|
- Every function has explicit type annotations (Python) or type signatures (TypeScript).
|
|
- Every public function has a docstring (Python — Google style) or JSDoc comment (TypeScript).
|
|
- No `any` in TypeScript. No `Any` in Python (unless justified with a comment).
|
|
- No magic numbers or strings — use named constants.
|
|
- No dead code, no commented-out blocks, no unused imports.
|
|
|
|
### 2.3 Keep It Small and Focused
|
|
|
|
- One function does one thing.
|
|
- One component per file.
|
|
- One service per domain.
|
|
- If a file grows beyond ~150 lines (components) or ~200 lines (services), split it.
|
|
|
|
### 2.4 Never Break Existing Code
|
|
|
|
- Before changing any file, understand what it does and who depends on it.
|
|
- Run the existing test suite before and after your changes. If tests fail after your change, fix them before moving on.
|
|
- Do not remove or rename public APIs without updating all callers.
|
|
|
|
### 2.5 Think Before You Code
|
|
|
|
- Read the task description carefully. If it is ambiguous, check [Features.md](Features.md) and [Architekture.md](Architekture.md) for clarification.
|
|
- Plan your changes before writing code. Identify which files are affected, which layers are involved, and what tests are needed.
|
|
- Prefer the simplest correct solution. Do not over-engineer.
|
|
|
|
---
|
|
|
|
## 3. Task Workflow
|
|
|
|
Repeat the following cycle for every task. Do not skip steps.
|
|
|
|
### Step 1 — Pick a Task
|
|
|
|
- Open `tasks.md` and pick the next unfinished task (highest priority first).
|
|
- Mark the task as **in progress**.
|
|
- Read the task description thoroughly. Understand the expected outcome before proceeding.
|
|
|
|
### Step 2 — Plan Your Steps
|
|
|
|
- Break the task into concrete implementation steps.
|
|
- Identify which files need to be created, modified, or deleted.
|
|
- Identify which layers are affected (router, service, repository, model, component, hook, page, type, etc.).
|
|
- Identify edge cases and error scenarios.
|
|
- Write down your plan before touching any code.
|
|
|
|
### Step 3 — Write Code
|
|
|
|
- Implement the feature or fix following the plan.
|
|
- Follow all rules from the relevant development docs:
|
|
- Backend → [Backend-Development.md](Backend-Development.md)
|
|
- Frontend → [Web-Development.md](Web-Development.md)
|
|
- Design → [Web-Design.md](Web-Design.md)
|
|
- Architecture → [Architekture.md](Architekture.md)
|
|
- Write clean, well-structured, fully typed code.
|
|
- Keep commits atomic — one logical change per commit.
|
|
|
|
### Step 4 — Add Logging
|
|
|
|
- Add structured log statements at key points in new or modified code.
|
|
- Backend: use **structlog** with contextual key-value pairs — never `print()`.
|
|
- Log at appropriate levels: `info` for operational events, `warning` for recoverable issues, `error` for failures.
|
|
- Never log sensitive data (passwords, tokens, session IDs).
|
|
|
|
### Step 5 — Write Tests
|
|
|
|
- Write tests for every new or changed piece of functionality.
|
|
- Backend: use `pytest` + `pytest-asyncio` + `httpx.AsyncClient`. See [Backend-Development.md § 9](Backend-Development.md).
|
|
- Frontend: test components and hooks according to the frontend test setup.
|
|
- Test the happy path **and** error/edge cases.
|
|
- Mock external dependencies — tests must never touch real infrastructure.
|
|
- Follow the naming pattern: `test_<unit>_<scenario>_<expected>`.
|
|
|
|
### Step 6 — Review Your Code
|
|
|
|
Run a thorough self-review before considering the task done. Check **all** of the following:
|
|
|
|
#### 6.1 — Warnings and Errors
|
|
|
|
- Backend: run `ruff check` and `mypy --strict` (or `pyright --strict`). Fix every warning and error.
|
|
- Frontend: run `tsc --noEmit` and `eslint`. Fix every warning and error.
|
|
- Zero warnings, zero errors — no exceptions.
|
|
|
|
#### 6.2 — Test Coverage
|
|
|
|
- Run the test suite with coverage enabled.
|
|
- Aim for **>80 % line coverage** overall.
|
|
- Critical paths (auth, banning, scheduling, API endpoints) must be **100 %** covered.
|
|
- If coverage is below the threshold, write additional tests before proceeding.
|
|
|
|
#### 6.3 — Coding Principles
|
|
|
|
Verify your code against the coding principles defined in [Backend-Development.md § 13](Backend-Development.md) and [Web-Development.md](Web-Development.md):
|
|
|
|
- [ ] **Clean Code** — Meaningful names, small functions, no magic values, guard clauses over deep nesting.
|
|
- [ ] **Separation of Concerns** — Each module has a single, well-defined responsibility. Layers are not mixed.
|
|
- [ ] **Single Responsibility Principle** — Every class and function has one reason to change.
|
|
- [ ] **DRY** — No duplicated logic. Shared behaviour is extracted.
|
|
- [ ] **KISS** — The simplest correct solution is used. No over-engineering.
|
|
- [ ] **Type Safety** — All types are explicit. No `any` / `Any`. No `# type: ignore` without justification.
|
|
|
|
#### 6.4 — Architecture Compliance
|
|
|
|
Verify against [Architekture.md](Architekture.md) and the project structure rules:
|
|
|
|
- [ ] Files are in the correct directories (routers in `routers/`, services in `services/`, components in `components/`, etc.).
|
|
- [ ] Dependencies flow in the right direction (routers → services → repositories; pages → components → hooks).
|
|
- [ ] No circular imports.
|
|
- [ ] No business logic in routers or components.
|
|
- [ ] No HTTP/framework concerns in services or repositories.
|
|
- [ ] Pydantic models separate request, response, and domain shapes.
|
|
- [ ] Frontend types live in `types/`, not scattered across components.
|
|
|
|
### Step 7 — Update Documentation
|
|
|
|
- If your change introduces new features, new endpoints, new components, or changes existing behaviour, update the relevant docs:
|
|
- [Features.md](Features.md) — if feature behaviour changed.
|
|
- [Architekture.md](Architekture.md) — if new modules, services, or data flows were added.
|
|
- [Backend-Development.md](Backend-Development.md) or [Web-Development.md](Web-Development.md) — if new conventions were established.
|
|
- Keep documentation accurate and in sync with the code. Outdated docs are worse than no docs.
|
|
|
|
### Step 8 — Mark Task Complete
|
|
|
|
- Open `tasks.md` and mark the task as **done**.
|
|
- Add a brief summary of what was implemented or changed.
|
|
|
|
### Step 9 — Commit
|
|
|
|
- Stage all changed files.
|
|
- Write a commit message in **imperative tense**, max 72 characters for the subject line.
|
|
- Good: `Add jail reload endpoint`
|
|
- Bad: `added stuff` / `WIP` / `fix`
|
|
- If the change is large, include a body explaining **why**, not just **what**.
|
|
- Branch naming: `feature/<short-description>`, `fix/<short-description>`, `chore/<short-description>`.
|
|
- Ensure the commit passes: linter, type checker, all tests.
|
|
|
|
### Step 10 — Next Task
|
|
|
|
- Return to **Step 1** and pick the next task.
|
|
|
|
---
|
|
|
|
## 4. Workflow Summary
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ 1. Pick task from tasks.md │
|
|
│ 2. Plan your steps │
|
|
│ 3. Write code │
|
|
│ 4. Add logging │
|
|
│ 5. Write tests │
|
|
│ 6. Review your code │
|
|
│ ├── 6.1 Check warnings & errors │
|
|
│ ├── 6.2 Check test coverage │
|
|
│ ├── 6.3 Check coding principles │
|
|
│ └── 6.4 Check architecture │
|
|
│ 7. Update documentation if needed │
|
|
│ 8. Mark task complete in tasks.md │
|
|
│ 9. Git commit │
|
|
│ 10. Pick next task ──────── loop ───┐ │
|
|
│ ▲ │ │
|
|
│ └───────────────────────────┘ │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 5. When You Are Stuck
|
|
|
|
- Re-read the task description and the relevant docs.
|
|
- Search the existing codebase for similar patterns — follow established conventions.
|
|
- Check the fail2ban source code in `fail2ban-master/` if you need to understand how fail2ban works internally.
|
|
- If a decision is genuinely ambiguous and no document covers it, choose the simplest option that is consistent with existing code and document your reasoning in a code comment.
|
|
|
|
---
|
|
|
|
## 6. What You Must Never Do
|
|
|
|
- **Never** commit code that does not compile or has type errors.
|
|
- **Never** commit code without tests.
|
|
- **Never** use libraries that are explicitly forbidden in the development docs.
|
|
- **Never** bypass the linter or type checker with blanket ignores.
|
|
- **Never** hard-code secrets, passwords, or tokens.
|
|
- **Never** push directly to `main` — always use feature branches.
|
|
- **Never** skip the review step — sloppy code compounds over time.
|
|
- **Never** leave a task half-done — finish it or revert it.
|