Document repo structure and conventions in CLAUDE.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-10 14:01:54 +02:00
parent 82e10aa31f
commit 2bc2c476c4
1 changed files with 42 additions and 0 deletions
@@ -8,3 +8,45 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 2. Simplest solution first. Always implement the simplest thing that could work. Do not add abstractions or flexibility that weren't explicitly requested.
 3. Don't touch unrelated code. If a file or function is not directly part of the current task, do not modify it, even if you think it could be improved.
 4. Flag uncertainty explicitly. If you are not confident about an approach or technical detail, say so before proceeding. Confidence without certainty causes more damage than admitting a gap.
+
+## Repository Purpose
+
+Infrastructure as Code and runbooks for Phytron's server infrastructure. Global configuration is done via Ansible; host-specific documentation, scripts, and files live under `server/`.
+
+## Structure
+
+```
+ansible/                    # Global settings & configuration for all servers
+  hosts.ini                 # Inventory: all existing and planned servers with IPs
+                            # (one group per host, group name == hostname)
+  group_vars/all.yml        # Defaults shared by all hosts
+  group_vars/<hostname>.yml # Per-host variables
+  run.yml                   # Main playbook
+  playbooks/                # Utility playbooks (update.yml, shutdown.yml)
+  roles/                    # Custom roles (e.g. nextcloud)
+  requirements.yml          # External Galaxy roles (geerlingguy.*, ...)
+  vars/vault.yml            # ansible-vault encrypted secrets — never commit plaintext
+  justfile                  # Task runner: just run HOST, just reqs, just vault ACTION
+
+server/<hostname>/          # Host-specific docs, scripts, files
+  README.md                 # Server documentation, filled gradually
+  manuals/                  # Runbooks, dated YYYYMMDD-<topic>.md
+  HW.md                     # Hardware specs (where relevant)
+```
+
+## Servers
+
+| Hostname         | IP            | Status                          |
+| ---------------- | ------------- | ------------------------------- |
+| phy-z-srv-jira   | 192.168.66.41 | configured                      |
+| phy-z-srv-cloud  | 192.168.66.66 | configured (Nextcloud)          |
+| phy-z-srv-git    | 192.168.66.67 | configured                      |
+| phy-z-dmz-sftp01 | 192.168.66.68 | configured                      |
+| phy-z-srv-gpu01  | 192.168.66.69 | planned — setup is the next task|
+
+## Conventions
+
+- Ansible commands run from `ansible/`, preferably via the `justfile` (e.g. `just run <HOST>`).
+- Secrets go into `ansible/vars/vault.yml`, encrypted with ansible-vault. Never commit plaintext secrets.
+- Dated documents (runbooks, assessments) use the `YYYYMMDD-<topic>.md` naming scheme.
+- New servers get: an entry in `hosts.ini`, a `group_vars/<hostname>.yml`, and a `server/<hostname>/` folder with a README.