Mateusz Suski
117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for Codex and other automated agents working in this repository.
|
|
|
|
## Purpose
|
|
|
|
This repository is a Linux/Unix infrastructure engineering portfolio. It shows practical operational work: incident response, troubleshooting, safe Bash tooling, Ansible hardening examples, storage workflows, runbooks, and platform/lab notes.
|
|
|
|
Treat it like internal operations tooling maintained by an infrastructure engineer. Preserve operational realism and avoid generic tutorial or template filler.
|
|
|
|
## Layout
|
|
|
|
- `infra-run/` - core operational tooling, Ansible, Bash scripts, runbooks, examples, and operations docs.
|
|
- `platform-projects/` - larger platform topics such as monitoring, storage, clustering, virtualization, and observability.
|
|
- `labs/` - experimental/lab environments for Kubernetes, Terraform, networking, CI/CD, Docker, and related work.
|
|
- `docs/codex/` - Codex workflow guidance, task templates, review checklist, and planning template.
|
|
- `scripts/` - repository validation helpers.
|
|
|
|
## Inspect First
|
|
|
|
Before editing, inspect the affected tree and nearby README files. Prefer:
|
|
|
|
```bash
|
|
rg --files
|
|
git status --short
|
|
sed -n '1,220p' <file>
|
|
```
|
|
|
|
Check existing style before introducing new structure. Keep changes small and reviewable.
|
|
|
|
## Validation
|
|
|
|
Run the broad repo check when practical:
|
|
|
|
```bash
|
|
./scripts/validate-repo.sh
|
|
```
|
|
|
|
Focused checks:
|
|
|
|
```bash
|
|
./scripts/check-bash.sh
|
|
./scripts/check-ansible.sh
|
|
./scripts/check-docs.sh
|
|
```
|
|
|
|
Optional strict mode fails when optional tools are missing:
|
|
|
|
```bash
|
|
STRICT=1 ./scripts/validate-repo.sh
|
|
```
|
|
|
|
Also run targeted checks for changed files, such as `bash -n`, `ansible-playbook --syntax-check`, or link checks when relevant.
|
|
|
|
## Bash Standards
|
|
|
|
- Use `#!/usr/bin/env bash`.
|
|
- Use `set -o errexit`, `set -o nounset`, and `set -o pipefail`.
|
|
- Validate input before using it.
|
|
- Handle missing commands clearly.
|
|
- Default to read-only or dry-run behavior.
|
|
- Require explicit `--execute` plus confirmation for destructive operations.
|
|
- Use clear `OK`, `WARNING`, and `CRITICAL` output.
|
|
- Exit codes: `0` OK, `1` operational issue, `2` invalid input or missing dependency.
|
|
- Keep scripts readable; separate discovery, pre-check, change, post-check, and reporting when it helps.
|
|
|
|
## Ansible Standards
|
|
|
|
- Keep playbooks short and roles simple.
|
|
- Prefer modules over `shell` or `command`.
|
|
- Use `shell` or `command` only when the module set cannot express the operation, and document why if risk is not obvious.
|
|
- Preserve check-mode and diff-mode friendliness where possible.
|
|
- Use handlers, tags, defaults, and validation tasks when they clarify operations.
|
|
- Keep inventory under `inventory/hosts.yml`, `group_vars/`, and `host_vars/`.
|
|
- Do not present selected hardening examples as complete compliance certification.
|
|
|
|
## Documentation Standards
|
|
|
|
- Explain what exists, what is planned, and what is intentionally not supported.
|
|
- Prefer runbook style: scope, pre-checks, execution guardrails, rollback thinking, post-checks, and evidence.
|
|
- Avoid marketing language, fake enterprise wording, and tutorial bloat.
|
|
- Update README files and `CHANGELOG.md` when adding meaningful behavior or structure.
|
|
|
|
## Safety Rules
|
|
|
|
- Do not run destructive commands.
|
|
- Do not rename large directories unless the benefit is clear and low-risk.
|
|
- Do not hide validation failures.
|
|
- Do not claim live production validation for sanitized examples.
|
|
- Do not add secrets, real hostnames, customer identifiers, or private infrastructure details.
|
|
- Do not turn placeholders into fake completed projects.
|
|
|
|
## PR and Review Expectations
|
|
|
|
- State the operational risk of the change.
|
|
- Include commands run and whether tools were missing.
|
|
- Review scripts for dry-run behavior, input validation, dependency handling, and rollback path.
|
|
- Review Ansible for idempotency, check-mode behavior, inventory targeting, tags, handlers, and module choice.
|
|
- Keep diffs focused.
|
|
|
|
## Definition of Done
|
|
|
|
- The change preserves the repository intent.
|
|
- Relevant docs are updated.
|
|
- Changed Bash scripts pass `bash -n`.
|
|
- Available validation helpers were run.
|
|
- Missing optional tools are reported.
|
|
- Any remaining risk or follow-up is documented.
|
|
|
|
## Do Not
|
|
|
|
- Do not add an "ultimate DevOps template" structure.
|
|
- Do not replace working simple Bash with unnecessary abstractions.
|
|
- Do not make examples appear production-certified.
|
|
- Do not add destructive behavior without `--execute`, confirmation, and clear rollback notes.
|
|
- Do not delete useful content unless it is clearly duplicate, broken, or misleading.
|