ddadmin
028817c555
- Зачем: - документация должна отражать только действующие правила и планы. - Что: - из AGENTS.md удалены устаревшие разделы о Git и общих требованиях. - из TODO.md удален прежний список задач. - Проверка: - git diff --cached --check.
91 lines
6.9 KiB
Markdown
91 lines
6.9 KiB
Markdown
# GEMINI.md - Project Context & Instructions
|
|
|
|
This repository contains personal dotfiles and configurations for a highly productive development environment, integrating Bash, Tmux, Vim, VS Code, and various AI assistants (Gemini CLI, Claude, Codex, Opencode).
|
|
|
|
## 📂 Project Overview
|
|
|
|
* **Type:** Non-Code Project (Dotfiles / Configuration)
|
|
* **Management:** Uses `stow` for Linux/WSL and `chezmoi` for Windows/WSL.
|
|
* **Key Focus:**
|
|
* Unified configuration across editors and terminals.
|
|
* Deep integration with AI tools via shared "skills".
|
|
* Automated environment setup (proxy handling, secret loading).
|
|
|
|
## 🛠 Key Components
|
|
|
|
### 1. Shell & Terminal (Bash & Tmux)
|
|
* **Bash:** Custom prompt (`.bash_prompt`), utility functions (`.bash_functions` like `proxy_on/off`), and core customizations (`.bash_custom`).
|
|
* **Tmux:** Dual prefix (`C-b` and `C-Space`), Vi-mode for copying, and optimized pane management.
|
|
* **Secrets:** Managed via `~/.env.secrets` (not tracked in Git).
|
|
|
|
### 2. Editors (Vim, VS Code, Zed)
|
|
* **Vim:** Minimalist `.vimrc`, 2-space indentation, leader-key mappings (`Space`).
|
|
* **VS Code (WSL):** Uses `server-env-setup` to automatically load secrets and configure proxy settings upon startup.
|
|
* **Zed:** Placeholder directory for future configuration.
|
|
|
|
### 3. AI Agents & Skills
|
|
* **Shared Skills:** Located in `agents/.agents/skills/`. This is the single source of truth for AI instructions.
|
|
* **Gemini CLI:** Configured via `gemini/.gemini/`.
|
|
* **Policies:** `readonly-commands.toml` allows critical commands like `git status`, `git diff`, and `git add` to run without confirmation.
|
|
* **Opencode:** MCP-based assistant configuration (`opencode.json`) with support for documentation, search, and web-reading.
|
|
* **Skill Bridges:** Symlinks are used to share skills across Claude, Codex, and Opencode.
|
|
|
|
## 🚀 Usage & Maintenance
|
|
|
|
### Deployment
|
|
* **Linux/WSL:** Use `stow <package_name>` from the root directory.
|
|
* **Windows:** Use `chezmoi apply`.
|
|
|
|
### Adding/Updating Skills
|
|
1. Modify files in `agents/.agents/skills/`.
|
|
2. Ensure symlinks in other tool directories are updated if new skills are added.
|
|
|
|
## 📋 TODO
|
|
|
|
Планы на будущее — см. [TODO.md](TODO.md).
|
|
|
|
## 🗣 Язык и рассуждения
|
|
|
|
Пиши на ясном русском языке. Иностранные слова оставляй только там, где у термина нет устоявшегося русского аналога: имена технологий и инструментов (Kafka, ClickHouse, Airflow) и названия из кода. Если для понятия есть обычное русское слово — используй его, не выдумывай транслитерации (пиши «приведение в соответствие», а не «реконсиляция»; «точка отсчёта», а не «origin»).
|
|
|
|
Документы, комментарии и объяснения держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании (помни про менти-неспециалиста). Если понятность и буквальная точность спорят — выбирай понятность. Правило касается и текста, и заголовков разделов.
|
|
|
|
Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов.
|
|
|
|
## Agent skills
|
|
|
|
### Issue tracker
|
|
|
|
Задачи хранятся в отслеживаемых Git Markdown-файлах текущей ветки под `.scratch/`. Перед `merge --no-ff` они удаляются. См. `docs/agents/issue-tracker.md`.
|
|
|
|
### Triage labels
|
|
|
|
Используются стандартные названия состояний triage. См. `docs/agents/triage-labels.md`.
|
|
|
|
### Domain docs
|
|
|
|
Используется схема single-context: корневой `CONTEXT.md` и общие ADR в `docs/adr/`. См. `docs/agents/domain.md`.
|
|
|
|
### Handoffs
|
|
|
|
Записки для продолжения работы в новой сессии — `.scratch/handoffs/YYYYMMDD-HHMM-<slug>.md` (одноразовые, коммитятся, уборка best-effort; скилл `/handoff` пишет сюда).
|
|
|
|
### `.scratch/` — рабочая зона; в master не переносится
|
|
|
|
Весь `.scratch/` — заметки по ходу дела: handoffs, PRD фич, нарезка задач. Коммитится (не в `.gitignore`), чтобы версионировать и передавать между сессиями, но в master ей делать нечего — это процесс, а не продукт.
|
|
|
|
Долговечное знание держим **вне** `.scratch/` (в `docs/`, `CONTEXT.md`). Прежде чем сливать фиче-ветку, убедись, что долговечная часть уже вынесена туда.
|
|
|
|
Слияние фиче-ветки в master:
|
|
|
|
1. Последним коммитом ветки — `git rm -r .scratch` (`chore: убрать рабочие заметки перед слиянием в master`).
|
|
2. `git merge --no-ff` в master.
|
|
|
|
`--no-ff` тянет все коммиты ветки в историю master, поэтому удалённый `.scratch/` остаётся достижим из merge-коммита и достаётся из истории в любой момент. Ничего не теряется — тег или архив не нужны.
|
|
|
|
## Субагенты и экономия контекста
|
|
|
|
Объёмную и механическую работу делегируем субагентам (Sonnet или аналогичная, в зависимости от сложности задачи), чтобы не засорять контекст основной сессии: проверки (реперы/линт/валидация), пакетные и файловые операции, отладка и прочее. Субагент сам читает «шумный» ввод-вывод и возвращает только результат.
|
|
|
|
- Мелочь делегировать не стоит — кроме случая, когда она даёт объёмный вывод: пусть субагент прочитает его у себя и вернёт выжимку.
|