diff --git a/agents.md b/agents.md
new file mode 100644
index 0000000..fd10c49
--- /dev/null
+++ b/agents.md
@@ -0,0 +1,175 @@
+# AGENTS.md
+
+## 🎯 Цель проекта
+
+Разработка локального HTTP/HTTPS прокси-сервера на Windows, который:
+
+* использует системные proxy-настройки (включая PAC/WPAD)
+* поднимает локальный proxy (127.0.0.1:PORT)
+* требует Basic-аутентификацию
+* проксирует весь трафик через системный proxy (upstream)
+* работает в оффлайн/ограниченной среде
+
+---
+
+## 🧱 Текущий стек
+
+* Язык: C#
+* Платформа: .NET 6+
+* ОС: Windows
+* Используемые API:
+
+  * WinHTTP (`WinHttpGetProxyForUrl`)
+  * TcpListener / TcpClient
+  * низкоуровневый HTTP parsing
+
+---
+
+## ✅ Уже реализовано
+
+* Локальный proxy сервер (TCP)
+* Поддержка HTTP
+* Поддержка HTTPS через CONNECT (туннель)
+* Basic Proxy Authentication
+* Чтение системного proxy через WinHTTP
+* Поддержка PAC/WPAD (через WinHttpGetProxyForUrl)
+* Проксирование через upstream proxy
+* Двунаправленный стриминг (Pump)
+
+---
+
+## ⚠️ Известные проблемы / ограничения
+
+### ❗ 1. Упрощённый HTTP parser
+
+* читает только первый пакет (8192 байт)
+* не обрабатывает:
+
+  * chunked encoding (входящий)
+  * большие POST body
+  * keep-alive корректно
+
+---
+
+### ❗ 2. Нет полноценной обработки proxy auth upstream
+
+* если upstream требует:
+
+  * NTLM / Kerberos → частично работает через WinHTTP
+  * Basic → не всегда прокидывается
+
+---
+
+### ❗ 3. Нет connection pooling
+
+* каждое соединение → новый TcpClient
+
+---
+
+### ❗ 4. Нет логирования
+
+* сложно дебажить поведение
+
+---
+
+### ❗ 5. Нет таймаутов / retry
+
+* возможны зависания
+
+---
+
+## 🔧 Следующие задачи (приоритет)
+
+### 🔥 HIGH
+
+* [ ] Полный HTTP parser (или перейти на HttpListener/Kestrel)
+* [ ] Корректная работа с большими body (streaming request)
+* [ ] Обработка chunked encoding
+* [ ] Таймауты на сокеты
+
+---
+
+### ⚙️ MEDIUM
+
+* [ ] Логирование (запросы, ошибки)
+* [ ] Ограничение количества соединений
+* [ ] Graceful shutdown
+
+---
+
+### 🚀 ADVANCED
+
+* [ ] Connection pooling
+* [ ] Кеширование CONNECT туннелей
+* [ ] Поддержка SOCKS5
+* [ ] MITM HTTPS (с генерацией сертификатов)
+
+---
+
+## 🧪 Как тестировать
+
+### curl
+
+curl -x http://user:pass@127.0.0.1:8888 http://example.com
+
+### HTTPS
+
+curl -x http://user:pass@127.0.0.1:8888 https://example.com -k
+
+---
+
+## 🐛 Типичные ошибки
+
+### "vite not executable"
+
+→ проблема несовместимости node_modules (macOS → Windows)
+
+### "Proxy 407"
+
+→ не передан Proxy-Authorization
+
+### "502 Bad Gateway"
+
+→ upstream proxy не принял CONNECT
+
+### timeout
+
+→ проблема с PAC / WinHTTP / сетью
+
+---
+
+## 🧠 Важные знания
+
+* node_modules нельзя переносить между ОС
+* WinHTTP ≠ WinINET (разные API)
+* PAC требует WinHttpGetProxyForUrl
+* CONNECT = raw TCP tunnel
+* Proxy chaining ломается без правильного handshake
+
+---
+
+## 📌 Контекст пользователя
+
+* Работает в оффлайн/ограниченной сети
+* Нужен полный контроль над proxy
+* Использует Windows
+* Требуется системная интеграция proxy
+
+---
+
+## 📎 Дальнейшее развитие
+
+Если продолжать:
+
+* перейти на async socket server с IOCP
+* добавить полноценный HTTP stack
+* или встроить готовый proxy engine (YARP / Kestrel)
+
+---
+
+## 💬 Примечание
+
+Это инженерный прототип прокси.
+Не production-ready, но уже близко к рабочему инструменту.
+
+Любые дальнейшие доработки — ориентироваться на реальные ошибки в сети.