From 6bc628517d5d704df3b28e9fae09991e0d47a1d0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 14:36:47 +0000
Subject: [PATCH 1/8] Initial plan


From a36b382eab39b89c15ce048e594287768e7e8e0e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 14:45:16 +0000
Subject: [PATCH 2/8] Add comprehensive Copilot instructions for NBS repository

Co-authored-by: jkuradobery <149376659+jkuradobery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 421 ++++++++++++++++++++++++++++++++
 1 file changed, 421 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000000..7f599d9f6bf
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,421 @@
+# Copilot Instructions for NBS Repository
+
+## Repository Overview
+
+**Network Block Store (NBS) and Network File Store (NFS)** is a Yandex Database (YDB) BlobStorage-based storage platform providing:
+- **Blockstore (NBS)**: Reliable thin-provisioned block devices with snapshot support, attachable via NBD, vhost-user-blk, or gRPC
+- **Filestore**: POSIX-compliant scalable filesystem mountable via FUSE or virtiofs for VMs
+- **Disk Manager**: Snapshot & image service providing control plane over NBS & Filestore
+
+**Repository Size**: ~2.2GB (source code ~40K+ C++ files, 7K+ Go files, 8K+ Python files)
+
+**Primary Languages**: C++ (majority), Go (disk_manager/tasks), Python (tests/tools)
+
+**Build System**: `ya` (Yandex build tool) - requires network access to download build tools from Yandex servers
+
+## Key Architecture Components
+
+### Main Project Directories
+- **`cloud/blockstore/`** - Network Block Store implementation (nbsd server, diskagentd, blockstore-client)
+- **`cloud/filestore/`** - Network File Store implementation (filestore-server, filestore-vhost, filestore-client)
+- **`cloud/disk_manager/`** - Snapshot/image service (Go codebase) with gRPC API
+- **`cloud/tasks/`** - Go task processor over YDB (foundation for Disk Manager)
+- **`cloud/storage/core/`** - Common libs used by NBS and Filestore
+- **`contrib/`** - Third-party OSS libraries with original LICENSE files
+- **`library/`** - Common algorithms and data structures
+- **`util/`** - Basic utilities (collections, strings, smart pointers, OS wrappers)
+- **`build/`** - Build system configuration files
+- **`example/`** - Local debugging setup scripts and instructions
+
+### Configuration Files (Root Level)
+- **`.clang-format`** - clang-format-18 configuration (REQUIRED for C++ formatting)
+- **`.clang-tidy`** - C++ linter configuration
+- **`ya.conf`** - ya build system configuration
+- **`.pre-commit-config.yaml`** - Pre-commit hooks (check-yaml, end-of-file-fixer, trailing-whitespace)
+- **`.githooks/pre-commit`** - Git pre-commit hook checking trailing whitespace
+- **`go.mod`** - Go module configuration
+
+## Build Instructions
+
+### Prerequisites
+
+**System Requirements:**
+- **Architecture**: x86_64 only
+- **OS**: Ubuntu 18.04/20.04/22.04 (other Linux distributions may work with effort)
+- **Disk Space**: At least 80GB free (recommend SSD for faster builds)
+- **RAM**: Each build thread uses ~1GB; linking uses up to 16GB; adjust threads accordingly
+- **Network**: Requires access to `devtools-registry.s3.yandex.net` for ya tool download
+
+**Required Packages:**
+```bash
+sudo apt-get update
+sudo apt-get install -y git wget gnupg lsb-release curl xz-utils \
+    tzdata python3-dev python3-pip antlr3 libidn11-dev file \
+    qemu-kvm qemu-utils dpkg-dev pigz pbzip2 gdb unzip \
+    libiconv libidn11 libaio
+```
+
+**Python Dependencies:**
+```bash
+sudo pip3 install pytest pytest-timeout pytest-xdist setproctitle \
+    grpcio grpcio-tools PyHamcrest tornado xmltodict pyarrow boto3 \
+    psutil PyGithub cryptography protobuf packaging six pyyaml
+```
+
+**Formatter (CRITICAL):**
+```bash
+sudo apt-get install clang-format-18
+```
+
+### Building with ya (Primary Build System)
+
+**IMPORTANT**: The `ya` script is a bootstrapping wrapper that downloads the actual build tool from Yandex servers. If you cannot access `devtools-registry.s3.yandex.net`, the build will fail.
+
+#### Initial Setup
+```bash
+# Clone with submodules
+git clone https://github.com/ydb-platform/nbs.git
+cd nbs
+git submodule update --init --recursive
+```
+
+#### Build All Components
+```bash
+# Build all NBS binaries (nbsd, diskagentd, blockstore-client, blockstore-nbd, ydbd)
+./ya make cloud/blockstore/buildall -r
+```
+
+**Build Time**: Initial build can take 30-60+ minutes depending on hardware and thread count.
+
+#### Build Specific Targets
+```bash
+# YDB storage backend
+./ya make contrib/ydb/apps/ydbd
+
+# NBS server (nbsd)
+./ya make cloud/blockstore/apps/server
+
+# Disk Agent (diskagentd)
+./ya make cloud/blockstore/apps/disk_agent
+
+# Client tools
+./ya make cloud/blockstore/apps/client
+./ya make cloud/blockstore/tools/nbd
+
+# Filestore server
+./ya make cloud/filestore/apps/server
+
+# Filestore vhost
+./ya make cloud/filestore/apps/vhost
+```
+
+**Output Binary Paths:**
+- `contrib/ydb/apps/ydbd/ydbd`
+- `cloud/blockstore/apps/server/nbsd`
+- `cloud/blockstore/apps/disk_agent/diskagentd`
+- `cloud/blockstore/apps/client/blockstore-client`
+- `cloud/blockstore/tools/nbd/blockstore-nbd`
+
+#### Common Build Options
+- **`-r`** - Build in release mode
+- **`-t`** - Run tests
+- **`--build=<type>`** - Build type: `debug`, `relwithdebinfo` (default), `release`
+- **`--sanitize=<sanitizer>`** - Enable sanitizer: `address`, `thread`, `memory`, `undefined`
+- **`-j<N>`** - Use N build threads (default: number of CPUs)
+- **`--keep-going`** - Continue on build errors
+- **`--stat`** - Show build statistics
+- **`--cache-size <size>`** - Set cache size (e.g., `512G`)
+
+### Building with CMake (Deprecated - May Not Work)
+
+CMake build is deprecated and may fail. Use only if ya build is unavailable.
+
+**Additional Dependencies for CMake:**
+```bash
+sudo apt-get install -y cmake clang-14 lld-14 ninja-build libaio-dev
+sudo pip3 install conan==1.59 grpcio-tools==1.57.0
+```
+
+**Build Steps:**
+```bash
+# Outside nbs directory
+mkdir nbs_build
+export CONAN_USER_HOME=./nbs_build
+cd nbs_build
+cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
+    -DCMAKE_TOOLCHAIN_FILE=../nbs/clang.toolchain \
+    ../nbs
+ninja
+```
+
+## Testing
+
+### Running Tests with ya
+
+**Run All Tests:**
+```bash
+./ya make -t cloud/blockstore
+./ya make -t cloud/filestore
+./ya make -t cloud/disk_manager
+```
+
+**Test Options:**
+- **`--test-size=<size>`** - Filter by size: `small`, `medium`, `large` (can combine: `small,medium`)
+- **`--test-type=<type>`** - Filter by type: `unittest`, `gtest`, `py3test`, `py2test`, `pytest`, `flake8`, `black`, `go_test`, `gofmt`, `clang_tidy`
+- **`--test-threads=<N>`** - Number of test threads (default: 28 in CI)
+- **`--run-all-tests`** - Run all tests including slow ones
+- **`--retest`** - Retry failed tests
+- **`--keep-going`** - Continue on test failures
+- **`--junit <file>`** - Generate JUnit XML report
+
+**Example Commands (from CI):**
+```bash
+# Build and run small/medium tests
+./ya make --test-size=small,medium \
+    --test-type=unittest,gtest,py3test \
+    --test-threads=64 --build=relwithdebinfo \
+    -t cloud/blockstore/ cloud/filestore/
+
+# Run with sanitizers (slower)
+./ya make --build=release --sanitize=address \
+    --test-size=small -t cloud/blockstore/
+```
+
+### Running Tests with CMake
+```bash
+cd nbs_build
+ctest
+```
+
+## Code Formatting and Linting
+
+### Format C++ Code (REQUIRED before commit)
+```bash
+# clang-format-18 uses .clang-format config automatically
+clang-format-18 -i <file>.cpp
+clang-format-18 -i <file>.h
+```
+
+**VSCode Setup**: Install `clangd` extension (llvm-vs-code-extensions.vscode-clangd)
+
+### Run Clang-Tidy
+```bash
+# Runs as part of test suite
+./ya make --test-type=clang_tidy -t cloud/blockstore/
+```
+
+### Pre-commit Checks
+```bash
+# Enable git hooks (checks trailing whitespace)
+git config core.hooksPath .githooks
+
+# Run pre-commit manually
+pre-commit run --all-files
+```
+
+### Python Linting
+```bash
+# Runs as part of test suite
+./ya make --test-type=flake8,black -t cloud/
+```
+
+### Go Formatting
+```bash
+# Runs as part of test suite
+./ya make --test-type=gofmt,go_test -t cloud/disk_manager/ cloud/tasks/
+```
+
+## Continuous Integration
+
+### GitHub Actions Workflows
+
+**Main PR Workflow** (`.github/workflows/pr.yaml`):
+- Triggers on PR to `main` (except docs, examples, `.md` files)
+- Checks membership or `ok-to-test` label for external contributors
+- Runs builds and tests on self-hosted runners (Nebius VMs)
+
+**Build and Test Workflow** (`.github/workflows/build_and_test_ya.yaml`):
+- Default targets: `cloud/blockstore/apps/`, `cloud/filestore/apps/`, `cloud/disk_manager/`, `cloud/tasks/`, `cloud/storage/`
+- Default test types: `unittest`, `clang_tidy`, `gtest`, `py3test`, `py2test`, `pytest`, `flake8`, `black`, `go_test`, `gofmt`
+- Default test sizes: `small`, `medium`, `large`
+- Build presets: `relwithdebinfo` (default), `release-asan`, `release-tsan`, `release-msan`, `release-ubsan`
+
+**PR Labels (affects CI behavior):**
+- `ok-to-test` - Required for external contributors to run CI
+- `large-tests` - Include large tests (default: small and medium only)
+- `blockstore`, `filestore`, `disk_manager`, `tasks` - Run tests only for specific projects
+- `asan`, `tsan` - Add address/thread sanitizer builds
+- `recheck` - Re-trigger checks without new commit (auto-removed)
+- `sleep` - Add 2-hour sleep for debugging
+- `allow-downgrade` - Allow dynamic VM preset downgrade if resources unavailable
+- `disable_truncate` - Don't truncate .err files (default: 1GiB limit)
+
+**Pre-commit Workflow** (`.github/workflows/pre-commit.yaml`):
+- Runs pre-commit hooks (check-yaml, end-of-file-fixer, trailing-whitespace)
+- Checks range: `origin/main..HEAD`
+
+### Test Artifacts and Logs
+
+Test results are uploaded to S3: `https://github-actions-s3.website.nemax.nebius.cloud/ydb-platform/nbs/PR-check/<run_id>/<attempt>/<arch>/`
+
+**Directory Structure:**
+- `build_logs/` - ya make build logs
+- `logs/` - Short test logs
+- `test_logs/` - Detailed ya test logs
+- `test_reports/` - JUnit reports and debug data
+- `summary/` - ya-test.html with test results
+- `test_data/` - Test data for failed tests (retained 1 week; other logs: 1 month)
+
+## Common Patterns and Project Structure
+
+### ya.make Files
+Each directory with code typically has a `ya.make` file defining the build target:
+- **`PROGRAM(...)`** - Executable binary
+- **`LIBRARY(...)`** - Static library
+- **`DLL(...)`** - Shared library
+- **`UNITTEST(...)`** - Unit test
+- **`PY3_PROGRAM(...)`** - Python 3 program
+- **`GO_LIBRARY(...)`** - Go library
+- **`GO_PROGRAM(...)`** - Go program
+
+**Example:**
+```
+PROGRAM(nbsd)
+SRCS(main.cpp)
+PEERDIR(
+    cloud/blockstore/libs/service
+    cloud/storage/core/libs/daemon
+)
+END()
+```
+
+### Code Organization
+- **Apps** (`apps/`) - Executable servers and clients
+- **Libs** (`libs/`) - Reusable libraries
+- **Tests** (`tests/`) - Integration tests
+- **Tools** (`tools/`) - Utility programs
+- **Config** (`config/`) - Proto configuration specs
+- **Public** (`public/`) - Public gRPC API
+- **Private** (`private/`) - Private gRPC API
+
+### Protocol Buffers
+Proto files are in `*/config`, `*/public`, `*/private` directories. They're auto-generated during build.
+
+## Local Development and Debugging
+
+### Quick Start Example (from `example/README.md`)
+```bash
+cd example
+
+# Setup environment (creates data directories, generates certs)
+./0-setup.sh
+
+# Start YDB storage (in separate terminal)
+./1-start_storage.sh
+
+# Initialize storage
+./2-init_storage.sh
+
+# Start NBS server (in separate terminal)
+./3-start_nbs.sh
+
+# Optional: Start disk agent for non-replicated disks (in separate terminal)
+./4-start_disk_agent.sh
+
+# Create a disk
+./5-create_disk.sh -k ssd  # Creates vol0
+
+# Attach disk via NBD
+sudo ./6-attach_disk.sh --disk-id vol0 -d /dev/nbd0
+
+# Test disk access
+sudo dd oflag=direct if=/dev/urandom of=/dev/nbd0 count=5 bs=4096
+sudo dd iflag=direct if=/dev/nbd0 of=./result.bin count=5 bs=4096
+
+# Monitor at http://localhost:8766/blockstore/service
+```
+
+**Disk Types Supported:**
+- `ssd` - Replicated network disk (vol0)
+- `nonreplicated` - Non-replicated disk (nbr0)
+- `mirror2` - 2x mirror (mrr0)
+- `mirror3` - 3x mirror (mrr1)
+
+### VSCode Setup
+```bash
+# Generate workspace
+./vscode_generate_workspace.sh
+code nbs.code-workspace
+
+# Enable git hooks
+git config core.hooksPath .githooks
+```
+
+**Recommended settings.json:**
+```json
+{
+    "files.trimTrailingWhitespace": true,
+    "files.trimFinalNewlines": true,
+    "files.insertFinalNewline": true,
+    "[go]": {
+        "editor.rulers": [{"column": 80, "color": "#ff0a0a"}]
+    }
+}
+```
+
+**For Debugging**: Enable static linkage in `~/.ya/ya.conf`:
+```
+[[target_platform]]
+platform_name = "default-linux-x86_64"
+build_type = "relwithdebinfo"
+
+[target_platform.flags]
+FORCE_STATIC_LINKING="yes"
+```
+
+## Known Issues and Workarounds
+
+### ya Build Tool Access
+**Issue**: `ya` script requires network access to Yandex servers to download build tools.
+**Workaround**: Ensure network access to `devtools-registry.s3.yandex.net` or work from an environment with cached ya tools.
+
+### Thread Sanitizer and gRPC
+**Issue**: gRPC has known issues with thread sanitizer.
+**Workaround**: Run with `TSAN_OPTIONS='report_atomic_races=0'`
+
+### Memory Requirements
+**Issue**: Linking may use up to 16GB RAM, causing OOM errors.
+**Workaround**: Reduce build threads using `-j<N>` flag or increase system RAM/swap.
+
+### Dynamic Link Errors
+**Issue**: Runtime library path not set when running built binaries.
+**Workaround**: Set `LD_LIBRARY_PATH` to include library directories (see filestore README example).
+
+## Summary: Agent Workflow for Making Changes
+
+1. **Always format code** with clang-format-18 for C++ changes
+2. **Run pre-commit checks** before committing (`git diff --check` or pre-commit hooks)
+3. **Build targets incrementally** - build specific target first to catch compile errors early:
+   ```bash
+   ./ya make cloud/blockstore/apps/server  # Build just nbsd
+   ```
+4. **Run relevant tests** for changed components:
+   ```bash
+   ./ya make -t --test-size=small,medium cloud/blockstore/libs/service
+   ```
+5. **Check all test types** if modifying core libs:
+   ```bash
+   ./ya make -t --test-type=unittest,gtest,clang_tidy <target>
+   ```
+6. **Verify changes locally** using example/ scripts if making changes to runtime behavior
+7. **Trust these instructions**: Only search for additional information if instructions are incomplete or found to be incorrect
+
+## Quick Reference
+
+**Build entire project:** `./ya make cloud/blockstore/buildall -r`
+**Run tests:** `./ya make -t cloud/blockstore/`
+**Format C++:** `clang-format-18 -i file.cpp`
+**Build with sanitizer:** `./ya make --sanitize=address cloud/blockstore/apps/server`
+**Local setup:** `cd example && ./0-setup.sh`
+
+For detailed documentation, see `/doc/REPOSITORY_STRUCTURE.md`

From 56f727b8277e7bc581a3d7e23ee05a0e3a6264b7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 14:48:18 +0000
Subject: [PATCH 3/8] Condense Copilot instructions to fit 2-page limit

Co-authored-by: jkuradobery <149376659+jkuradobery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 444 ++++++--------------------------
 1 file changed, 75 insertions(+), 369 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 7f599d9f6bf..fe02749bcbb 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,421 +1,127 @@
 # Copilot Instructions for NBS Repository
 
-## Repository Overview
+## Overview
+Network Block Store (NBS) and Network File Store: YDB BlobStorage-based storage platform providing block devices (NBD/vhost-blk/gRPC) and POSIX filesystem (FUSE/virtiofs). ~2.2GB repo with C++ (40K+ files), Go (disk_manager/tasks), Python (tests). Build system: `ya` (requires `devtools-registry.s3.yandex.net` access).
 
-**Network Block Store (NBS) and Network File Store (NFS)** is a Yandex Database (YDB) BlobStorage-based storage platform providing:
-- **Blockstore (NBS)**: Reliable thin-provisioned block devices with snapshot support, attachable via NBD, vhost-user-blk, or gRPC
-- **Filestore**: POSIX-compliant scalable filesystem mountable via FUSE or virtiofs for VMs
-- **Disk Manager**: Snapshot & image service providing control plane over NBS & Filestore
+**Key Directories:** `cloud/blockstore/` (NBS), `cloud/filestore/` (NFS), `cloud/disk_manager/` (Go snapshot service), `cloud/storage/core/` (common libs), `contrib/` (OSS deps), `example/` (local dev scripts).
 
-**Repository Size**: ~2.2GB (source code ~40K+ C++ files, 7K+ Go files, 8K+ Python files)
+**Root Configs:** `.clang-format` (clang-format-18 REQUIRED), `.clang-tidy`, `ya.conf`, `.pre-commit-config.yaml`, `.githooks/pre-commit` (whitespace checks).
 
-**Primary Languages**: C++ (majority), Go (disk_manager/tasks), Python (tests/tools)
-
-**Build System**: `ya` (Yandex build tool) - requires network access to download build tools from Yandex servers
-
-## Key Architecture Components
-
-### Main Project Directories
-- **`cloud/blockstore/`** - Network Block Store implementation (nbsd server, diskagentd, blockstore-client)
-- **`cloud/filestore/`** - Network File Store implementation (filestore-server, filestore-vhost, filestore-client)
-- **`cloud/disk_manager/`** - Snapshot/image service (Go codebase) with gRPC API
-- **`cloud/tasks/`** - Go task processor over YDB (foundation for Disk Manager)
-- **`cloud/storage/core/`** - Common libs used by NBS and Filestore
-- **`contrib/`** - Third-party OSS libraries with original LICENSE files
-- **`library/`** - Common algorithms and data structures
-- **`util/`** - Basic utilities (collections, strings, smart pointers, OS wrappers)
-- **`build/`** - Build system configuration files
-- **`example/`** - Local debugging setup scripts and instructions
-
-### Configuration Files (Root Level)
-- **`.clang-format`** - clang-format-18 configuration (REQUIRED for C++ formatting)
-- **`.clang-tidy`** - C++ linter configuration
-- **`ya.conf`** - ya build system configuration
-- **`.pre-commit-config.yaml`** - Pre-commit hooks (check-yaml, end-of-file-fixer, trailing-whitespace)
-- **`.githooks/pre-commit`** - Git pre-commit hook checking trailing whitespace
-- **`go.mod`** - Go module configuration
-
-## Build Instructions
+## Build & Test
 
 ### Prerequisites
-
-**System Requirements:**
-- **Architecture**: x86_64 only
-- **OS**: Ubuntu 18.04/20.04/22.04 (other Linux distributions may work with effort)
-- **Disk Space**: At least 80GB free (recommend SSD for faster builds)
-- **RAM**: Each build thread uses ~1GB; linking uses up to 16GB; adjust threads accordingly
-- **Network**: Requires access to `devtools-registry.s3.yandex.net` for ya tool download
-
-**Required Packages:**
-```bash
-sudo apt-get update
-sudo apt-get install -y git wget gnupg lsb-release curl xz-utils \
-    tzdata python3-dev python3-pip antlr3 libidn11-dev file \
-    qemu-kvm qemu-utils dpkg-dev pigz pbzip2 gdb unzip \
-    libiconv libidn11 libaio
-```
-
-**Python Dependencies:**
-```bash
-sudo pip3 install pytest pytest-timeout pytest-xdist setproctitle \
-    grpcio grpcio-tools PyHamcrest tornado xmltodict pyarrow boto3 \
-    psutil PyGithub cryptography protobuf packaging six pyyaml
-```
-
-**Formatter (CRITICAL):**
+**System:** x86_64, Ubuntu 18.04+, 80GB+ disk (SSD), 16GB+ RAM. **Network:** Access to `devtools-registry.s3.yandex.net` required.
 ```bash
-sudo apt-get install clang-format-18
+# Install deps
+sudo apt-get install -y git python3-pip antlr3 libidn11-dev qemu-kvm libaio clang-format-18
+sudo pip3 install pytest grpcio grpcio-tools boto3 psutil PyGithub cryptography protobuf
 ```
 
-### Building with ya (Primary Build System)
-
-**IMPORTANT**: The `ya` script is a bootstrapping wrapper that downloads the actual build tool from Yandex servers. If you cannot access `devtools-registry.s3.yandex.net`, the build will fail.
-
-#### Initial Setup
+### Build Commands
 ```bash
-# Clone with submodules
-git clone https://github.com/ydb-platform/nbs.git
-cd nbs
+# Clone and build all
+git clone https://github.com/ydb-platform/nbs.git && cd nbs
 git submodule update --init --recursive
-```
+./ya make cloud/blockstore/buildall -r  # 30-60+ min initial build
 
-#### Build All Components
-```bash
-# Build all NBS binaries (nbsd, diskagentd, blockstore-client, blockstore-nbd, ydbd)
-./ya make cloud/blockstore/buildall -r
+# Build specific targets
+./ya make cloud/blockstore/apps/server     # nbsd → cloud/blockstore/apps/server/nbsd
+./ya make cloud/blockstore/apps/disk_agent # diskagentd
+./ya make cloud/blockstore/apps/client     # blockstore-client
+./ya make cloud/filestore/apps/server      # filestore-server
 ```
 
-**Build Time**: Initial build can take 30-60+ minutes depending on hardware and thread count.
+**Options:** `-r` (release), `-t` (run tests), `-j<N>` (threads), `--build=<debug|relwithdebinfo|release>`, `--sanitize=<address|thread|memory|undefined>`, `--keep-going`, `--stat`
 
-#### Build Specific Targets
+### Testing
 ```bash
-# YDB storage backend
-./ya make contrib/ydb/apps/ydbd
-
-# NBS server (nbsd)
-./ya make cloud/blockstore/apps/server
-
-# Disk Agent (diskagentd)
-./ya make cloud/blockstore/apps/disk_agent
-
-# Client tools
-./ya make cloud/blockstore/apps/client
-./ya make cloud/blockstore/tools/nbd
-
-# Filestore server
-./ya make cloud/filestore/apps/server
-
-# Filestore vhost
-./ya make cloud/filestore/apps/vhost
-```
-
-**Output Binary Paths:**
-- `contrib/ydb/apps/ydbd/ydbd`
-- `cloud/blockstore/apps/server/nbsd`
-- `cloud/blockstore/apps/disk_agent/diskagentd`
-- `cloud/blockstore/apps/client/blockstore-client`
-- `cloud/blockstore/tools/nbd/blockstore-nbd`
-
-#### Common Build Options
-- **`-r`** - Build in release mode
-- **`-t`** - Run tests
-- **`--build=<type>`** - Build type: `debug`, `relwithdebinfo` (default), `release`
-- **`--sanitize=<sanitizer>`** - Enable sanitizer: `address`, `thread`, `memory`, `undefined`
-- **`-j<N>`** - Use N build threads (default: number of CPUs)
-- **`--keep-going`** - Continue on build errors
-- **`--stat`** - Show build statistics
-- **`--cache-size <size>`** - Set cache size (e.g., `512G`)
-
-### Building with CMake (Deprecated - May Not Work)
-
-CMake build is deprecated and may fail. Use only if ya build is unavailable.
-
-**Additional Dependencies for CMake:**
-```bash
-sudo apt-get install -y cmake clang-14 lld-14 ninja-build libaio-dev
-sudo pip3 install conan==1.59 grpcio-tools==1.57.0
-```
-
-**Build Steps:**
-```bash
-# Outside nbs directory
-mkdir nbs_build
-export CONAN_USER_HOME=./nbs_build
-cd nbs_build
-cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
-    -DCMAKE_TOOLCHAIN_FILE=../nbs/clang.toolchain \
-    ../nbs
-ninja
-```
-
-## Testing
-
-### Running Tests with ya
-
-**Run All Tests:**
-```bash
-./ya make -t cloud/blockstore
-./ya make -t cloud/filestore
-./ya make -t cloud/disk_manager
-```
-
-**Test Options:**
-- **`--test-size=<size>`** - Filter by size: `small`, `medium`, `large` (can combine: `small,medium`)
-- **`--test-type=<type>`** - Filter by type: `unittest`, `gtest`, `py3test`, `py2test`, `pytest`, `flake8`, `black`, `go_test`, `gofmt`, `clang_tidy`
-- **`--test-threads=<N>`** - Number of test threads (default: 28 in CI)
-- **`--run-all-tests`** - Run all tests including slow ones
-- **`--retest`** - Retry failed tests
-- **`--keep-going`** - Continue on test failures
-- **`--junit <file>`** - Generate JUnit XML report
-
-**Example Commands (from CI):**
-```bash
-# Build and run small/medium tests
-./ya make --test-size=small,medium \
-    --test-type=unittest,gtest,py3test \
-    --test-threads=64 --build=relwithdebinfo \
-    -t cloud/blockstore/ cloud/filestore/
-
-# Run with sanitizers (slower)
-./ya make --build=release --sanitize=address \
-    --test-size=small -t cloud/blockstore/
-```
+# Run tests for component
+./ya make -t cloud/blockstore/
+./ya make -t --test-size=small,medium --test-type=unittest,gtest,py3test cloud/blockstore/
 
-### Running Tests with CMake
-```bash
-cd nbs_build
-ctest
+# Test types: unittest, gtest, py3test, py2test, pytest, flake8, black, go_test, gofmt, clang_tidy
+# Test sizes: small, medium, large
 ```
 
-## Code Formatting and Linting
-
-### Format C++ Code (REQUIRED before commit)
-```bash
-# clang-format-18 uses .clang-format config automatically
-clang-format-18 -i <file>.cpp
-clang-format-18 -i <file>.h
-```
+**Common options:** `--test-threads=<N>` (default CI: 64), `--run-all-tests`, `--retest`, `--junit <file>`
 
-**VSCode Setup**: Install `clangd` extension (llvm-vs-code-extensions.vscode-clangd)
+## Code Quality & CI
 
-### Run Clang-Tidy
+### Format & Lint (REQUIRED before commit)
 ```bash
-# Runs as part of test suite
-./ya make --test-type=clang_tidy -t cloud/blockstore/
-```
+# C++ formatting (MANDATORY)
+clang-format-18 -i file.cpp file.h
 
-### Pre-commit Checks
-```bash
 # Enable git hooks (checks trailing whitespace)
 git config core.hooksPath .githooks
 
-# Run pre-commit manually
+# Pre-commit checks
 pre-commit run --all-files
 ```
 
-### Python Linting
-```bash
-# Runs as part of test suite
-./ya make --test-type=flake8,black -t cloud/
-```
-
-### Go Formatting
-```bash
-# Runs as part of test suite
-./ya make --test-type=gofmt,go_test -t cloud/disk_manager/ cloud/tasks/
-```
-
-## Continuous Integration
-
-### GitHub Actions Workflows
-
-**Main PR Workflow** (`.github/workflows/pr.yaml`):
-- Triggers on PR to `main` (except docs, examples, `.md` files)
-- Checks membership or `ok-to-test` label for external contributors
-- Runs builds and tests on self-hosted runners (Nebius VMs)
-
-**Build and Test Workflow** (`.github/workflows/build_and_test_ya.yaml`):
-- Default targets: `cloud/blockstore/apps/`, `cloud/filestore/apps/`, `cloud/disk_manager/`, `cloud/tasks/`, `cloud/storage/`
-- Default test types: `unittest`, `clang_tidy`, `gtest`, `py3test`, `py2test`, `pytest`, `flake8`, `black`, `go_test`, `gofmt`
-- Default test sizes: `small`, `medium`, `large`
-- Build presets: `relwithdebinfo` (default), `release-asan`, `release-tsan`, `release-msan`, `release-ubsan`
-
-**PR Labels (affects CI behavior):**
-- `ok-to-test` - Required for external contributors to run CI
-- `large-tests` - Include large tests (default: small and medium only)
-- `blockstore`, `filestore`, `disk_manager`, `tasks` - Run tests only for specific projects
-- `asan`, `tsan` - Add address/thread sanitizer builds
-- `recheck` - Re-trigger checks without new commit (auto-removed)
-- `sleep` - Add 2-hour sleep for debugging
-- `allow-downgrade` - Allow dynamic VM preset downgrade if resources unavailable
-- `disable_truncate` - Don't truncate .err files (default: 1GiB limit)
-
-**Pre-commit Workflow** (`.github/workflows/pre-commit.yaml`):
-- Runs pre-commit hooks (check-yaml, end-of-file-fixer, trailing-whitespace)
-- Checks range: `origin/main..HEAD`
+### CI Workflows
+**Main PR:** `.github/workflows/pr.yaml` - Triggers on PR to `main` (skips docs/examples/md files). Requires org membership or `ok-to-test` label for external contributors.
 
-### Test Artifacts and Logs
+**Build/Test:** `.github/workflows/build_and_test_ya.yaml` - Targets: `cloud/blockstore/apps/`, `cloud/filestore/apps/`, `cloud/disk_manager/`, `cloud/tasks/`, `cloud/storage/`. Default tests: `unittest,clang_tidy,gtest,py3test,py2test,pytest,flake8,black,go_test,gofmt`. Sizes: `small,medium,large`. Preset: `relwithdebinfo`.
 
-Test results are uploaded to S3: `https://github-actions-s3.website.nemax.nebius.cloud/ydb-platform/nbs/PR-check/<run_id>/<attempt>/<arch>/`
+**PR Labels:**
+- `ok-to-test` - Enable CI for external contributors
+- `large-tests` - Include large tests (default: small+medium only)
+- `blockstore`/`filestore`/`disk_manager`/`tasks` - Test specific projects only
+- `asan`/`tsan` - Add sanitizer builds
+- `recheck` - Re-trigger without new commit
 
-**Directory Structure:**
-- `build_logs/` - ya make build logs
-- `logs/` - Short test logs
-- `test_logs/` - Detailed ya test logs
-- `test_reports/` - JUnit reports and debug data
-- `summary/` - ya-test.html with test results
-- `test_data/` - Test data for failed tests (retained 1 week; other logs: 1 month)
-
-## Common Patterns and Project Structure
-
-### ya.make Files
-Each directory with code typically has a `ya.make` file defining the build target:
-- **`PROGRAM(...)`** - Executable binary
-- **`LIBRARY(...)`** - Static library
-- **`DLL(...)`** - Shared library
-- **`UNITTEST(...)`** - Unit test
-- **`PY3_PROGRAM(...)`** - Python 3 program
-- **`GO_LIBRARY(...)`** - Go library
-- **`GO_PROGRAM(...)`** - Go program
-
-**Example:**
-```
-PROGRAM(nbsd)
-SRCS(main.cpp)
-PEERDIR(
-    cloud/blockstore/libs/service
-    cloud/storage/core/libs/daemon
-)
-END()
-```
+**Test Artifacts:** S3 at `https://github-actions-s3.website.nemax.nebius.cloud/ydb-platform/nbs/PR-check/<run_id>/...` - See `build_logs/`, `test_logs/`, `summary/ya-test.html`
 
-### Code Organization
-- **Apps** (`apps/`) - Executable servers and clients
-- **Libs** (`libs/`) - Reusable libraries
-- **Tests** (`tests/`) - Integration tests
-- **Tools** (`tools/`) - Utility programs
-- **Config** (`config/`) - Proto configuration specs
-- **Public** (`public/`) - Public gRPC API
-- **Private** (`private/`) - Private gRPC API
+## Local Development
 
-### Protocol Buffers
-Proto files are in `*/config`, `*/public`, `*/private` directories. They're auto-generated during build.
-
-## Local Development and Debugging
-
-### Quick Start Example (from `example/README.md`)
+### Quick Setup (example/ directory)
 ```bash
 cd example
-
-# Setup environment (creates data directories, generates certs)
-./0-setup.sh
-
-# Start YDB storage (in separate terminal)
-./1-start_storage.sh
-
-# Initialize storage
-./2-init_storage.sh
-
-# Start NBS server (in separate terminal)
-./3-start_nbs.sh
-
-# Optional: Start disk agent for non-replicated disks (in separate terminal)
-./4-start_disk_agent.sh
-
-# Create a disk
-./5-create_disk.sh -k ssd  # Creates vol0
-
-# Attach disk via NBD
+./0-setup.sh                           # Setup env, generate certs, create data dirs
+./1-start_storage.sh                   # Start YDB storage (separate terminal)
+./2-init_storage.sh                    # Initialize storage
+./3-start_nbs.sh                       # Start NBS server (separate terminal)
+./4-start_disk_agent.sh                # Optional: for non-replicated disks
+./5-create_disk.sh -k ssd              # Create vol0 (ssd/nonreplicated/mirror2/mirror3)
 sudo ./6-attach_disk.sh --disk-id vol0 -d /dev/nbd0
-
-# Test disk access
-sudo dd oflag=direct if=/dev/urandom of=/dev/nbd0 count=5 bs=4096
-sudo dd iflag=direct if=/dev/nbd0 of=./result.bin count=5 bs=4096
-
-# Monitor at http://localhost:8766/blockstore/service
+# Test: sudo dd oflag=direct if=/dev/urandom of=/dev/nbd0 count=5 bs=4096
+# Monitor: http://localhost:8766/blockstore/service
 ```
 
-**Disk Types Supported:**
-- `ssd` - Replicated network disk (vol0)
-- `nonreplicated` - Non-replicated disk (nbr0)
-- `mirror2` - 2x mirror (mrr0)
-- `mirror3` - 3x mirror (mrr1)
-
 ### VSCode Setup
 ```bash
-# Generate workspace
-./vscode_generate_workspace.sh
-code nbs.code-workspace
-
-# Enable git hooks
-git config core.hooksPath .githooks
-```
-
-**Recommended settings.json:**
-```json
-{
-    "files.trimTrailingWhitespace": true,
-    "files.trimFinalNewlines": true,
-    "files.insertFinalNewline": true,
-    "[go]": {
-        "editor.rulers": [{"column": 80, "color": "#ff0a0a"}]
-    }
-}
+./vscode_generate_workspace.sh && code nbs.code-workspace
+# Install clangd extension. For debugging, add to ~/.ya/ya.conf:
+# [[target_platform]]
+# platform_name = "default-linux-x86_64"
+# build_type = "relwithdebinfo"
+# [target_platform.flags]
+# FORCE_STATIC_LINKING="yes"
 ```
 
-**For Debugging**: Enable static linkage in `~/.ya/ya.conf`:
-```
-[[target_platform]]
-platform_name = "default-linux-x86_64"
-build_type = "relwithdebinfo"
-
-[target_platform.flags]
-FORCE_STATIC_LINKING="yes"
-```
-
-## Known Issues and Workarounds
-
-### ya Build Tool Access
-**Issue**: `ya` script requires network access to Yandex servers to download build tools.
-**Workaround**: Ensure network access to `devtools-registry.s3.yandex.net` or work from an environment with cached ya tools.
+## Project Structure
 
-### Thread Sanitizer and gRPC
-**Issue**: gRPC has known issues with thread sanitizer.
-**Workaround**: Run with `TSAN_OPTIONS='report_atomic_races=0'`
+**ya.make files** define build targets: `PROGRAM()`, `LIBRARY()`, `UNITTEST()`, `PY3_PROGRAM()`, `GO_PROGRAM()`, etc. Each uses `PEERDIR()` for dependencies.
 
-### Memory Requirements
-**Issue**: Linking may use up to 16GB RAM, causing OOM errors.
-**Workaround**: Reduce build threads using `-j<N>` flag or increase system RAM/swap.
+**Code Organization:** `apps/` (executables), `libs/` (libraries), `tests/` (integration), `tools/` (utilities), `config/` (protos), `public/` (gRPC API), `private/` (internal gRPC).
 
-### Dynamic Link Errors
-**Issue**: Runtime library path not set when running built binaries.
-**Workaround**: Set `LD_LIBRARY_PATH` to include library directories (see filestore README example).
+## Known Issues & Workarounds
 
-## Summary: Agent Workflow for Making Changes
+1. **ya tool access:** Requires `devtools-registry.s3.yandex.net` - ensure network access or use cached ya tools
+2. **TSAN + gRPC:** Run with `TSAN_OPTIONS='report_atomic_races=0'`
+3. **OOM during linking:** Reduce threads with `-j<N>` or increase RAM/swap
+4. **Runtime libs:** Set `LD_LIBRARY_PATH` for built binaries if needed
+5. **CMake build:** Deprecated, may not work - use ya
 
-1. **Always format code** with clang-format-18 for C++ changes
-2. **Run pre-commit checks** before committing (`git diff --check` or pre-commit hooks)
-3. **Build targets incrementally** - build specific target first to catch compile errors early:
-   ```bash
-   ./ya make cloud/blockstore/apps/server  # Build just nbsd
-   ```
-4. **Run relevant tests** for changed components:
-   ```bash
-   ./ya make -t --test-size=small,medium cloud/blockstore/libs/service
-   ```
-5. **Check all test types** if modifying core libs:
-   ```bash
-   ./ya make -t --test-type=unittest,gtest,clang_tidy <target>
-   ```
-6. **Verify changes locally** using example/ scripts if making changes to runtime behavior
-7. **Trust these instructions**: Only search for additional information if instructions are incomplete or found to be incorrect
+## Agent Workflow
 
-## Quick Reference
+1. **Format C++ with clang-format-18** (mandatory)
+2. **Run pre-commit checks** (`git diff --check` or hooks)
+3. **Build incrementally:** `./ya make cloud/blockstore/apps/server` to catch errors early
+4. **Test changed components:** `./ya make -t --test-size=small,medium cloud/blockstore/libs/service`
+5. **Verify locally** using `example/` scripts for runtime changes
+6. **Trust these instructions** - only search if incomplete/incorrect
 
-**Build entire project:** `./ya make cloud/blockstore/buildall -r`
-**Run tests:** `./ya make -t cloud/blockstore/`
-**Format C++:** `clang-format-18 -i file.cpp`
-**Build with sanitizer:** `./ya make --sanitize=address cloud/blockstore/apps/server`
-**Local setup:** `cd example && ./0-setup.sh`
+**Quick Ref:** Build all: `./ya make cloud/blockstore/buildall -r` | Test: `./ya make -t cloud/blockstore/` | Format: `clang-format-18 -i file.cpp` | Sanitizer: `./ya make --sanitize=address <target>` | Docs: `/doc/REPOSITORY_STRUCTURE.md`
 
-For detailed documentation, see `/doc/REPOSITORY_STRUCTURE.md`

From 1ffc9839aabcd3182878405c3e2162d87cb1bbeb Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 14:49:19 +0000
Subject: [PATCH 4/8] Fix file path reference and remove trailing blank lines

Co-authored-by: jkuradobery <149376659+jkuradobery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index fe02749bcbb..ea8cf5aebf2 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -123,5 +123,4 @@ sudo ./6-attach_disk.sh --disk-id vol0 -d /dev/nbd0
 5. **Verify locally** using `example/` scripts for runtime changes
 6. **Trust these instructions** - only search if incomplete/incorrect
 
-**Quick Ref:** Build all: `./ya make cloud/blockstore/buildall -r` | Test: `./ya make -t cloud/blockstore/` | Format: `clang-format-18 -i file.cpp` | Sanitizer: `./ya make --sanitize=address <target>` | Docs: `/doc/REPOSITORY_STRUCTURE.md`
-
+**Quick Ref:** Build all: `./ya make cloud/blockstore/buildall -r` | Test: `./ya make -t cloud/blockstore/` | Format: `clang-format-18 -i file.cpp` | Sanitizer: `./ya make --sanitize=address <target>` | Docs: `doc/REPOSITORY_STRUCTURE.md`

From 9dca759f07f7da11c77b432fbfc982578ca491e8 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 14:50:19 +0000
Subject: [PATCH 5/8] Address code review feedback: improve readability and
 safety

Co-authored-by: jkuradobery <149376659+jkuradobery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index ea8cf5aebf2..7bddb471776 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,7 +1,11 @@
 # Copilot Instructions for NBS Repository
 
 ## Overview
-Network Block Store (NBS) and Network File Store: YDB BlobStorage-based storage platform providing block devices (NBD/vhost-blk/gRPC) and POSIX filesystem (FUSE/virtiofs). ~2.2GB repo with C++ (40K+ files), Go (disk_manager/tasks), Python (tests). Build system: `ya` (requires `devtools-registry.s3.yandex.net` access).
+Network Block Store (NBS) and Network File Store: YDB BlobStorage-based storage platform.
+- **NBS**: Block devices via NBD/vhost-blk/gRPC
+- **NFS**: POSIX filesystem via FUSE/virtiofs
+- **Size**: ~2.2GB repo with C++ (40K+ files), Go (disk_manager/tasks), Python (tests)
+- **Build**: `ya` tool (requires `devtools-registry.s3.yandex.net` access)
 
 **Key Directories:** `cloud/blockstore/` (NBS), `cloud/filestore/` (NFS), `cloud/disk_manager/` (Go snapshot service), `cloud/storage/core/` (common libs), `contrib/` (OSS deps), `example/` (local dev scripts).
 
@@ -10,7 +14,7 @@ Network Block Store (NBS) and Network File Store: YDB BlobStorage-based storage
 ## Build & Test
 
 ### Prerequisites
-**System:** x86_64, Ubuntu 18.04+, 80GB+ disk (SSD), 16GB+ RAM. **Network:** Access to `devtools-registry.s3.yandex.net` required.
+**System:** x86_64, Ubuntu 20.04+ (18.04 EOL but may work), 80GB+ disk (SSD), 16GB+ RAM. **Network:** Access to `devtools-registry.s3.yandex.net` required.
 ```bash
 # Install deps
 sudo apt-get install -y git python3-pip antlr3 libidn11-dev qemu-kvm libaio clang-format-18
@@ -85,7 +89,7 @@ cd example
 ./4-start_disk_agent.sh                # Optional: for non-replicated disks
 ./5-create_disk.sh -k ssd              # Create vol0 (ssd/nonreplicated/mirror2/mirror3)
 sudo ./6-attach_disk.sh --disk-id vol0 -d /dev/nbd0
-# Test: sudo dd oflag=direct if=/dev/urandom of=/dev/nbd0 count=5 bs=4096
+# Test (WARNING: destructive, only use on test disks): sudo dd oflag=direct if=/dev/urandom of=/dev/nbd0 count=5 bs=4096
 # Monitor: http://localhost:8766/blockstore/service
 ```
 

From fdc8ab39fc9f378f1939f7bb8fd787a884a05a5f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 14:51:49 +0000
Subject: [PATCH 6/8] Clarify how to find S3 test artifact URLs

Co-authored-by: jkuradobery <149376659+jkuradobery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 7bddb471776..6a45e41dab2 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -75,7 +75,7 @@ pre-commit run --all-files
 - `asan`/`tsan` - Add sanitizer builds
 - `recheck` - Re-trigger without new commit
 
-**Test Artifacts:** S3 at `https://github-actions-s3.website.nemax.nebius.cloud/ydb-platform/nbs/PR-check/<run_id>/...` - See `build_logs/`, `test_logs/`, `summary/ya-test.html`
+**Test Artifacts:** S3 at `https://github-actions-s3.website.nemax.nebius.cloud/ydb-platform/nbs/PR-check/<run_id>/...` (find run_id in Actions tab) - See `build_logs/`, `test_logs/`, `summary/ya-test.html`
 
 ## Local Development
 

From cbc6bb5e8eb4d17816f364ab6c3d7dc7d76af113 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 15:46:01 +0000
Subject: [PATCH 7/8] Enhance Copilot instructions with detailed code style and
 review guidance

Co-authored-by: jkuradobery <149376659+jkuradobery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 58 ++++++++++++++++++++++++---------
 1 file changed, 43 insertions(+), 15 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 6a45e41dab2..1624c4f815b 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -49,21 +49,41 @@ git submodule update --init --recursive
 
 **Common options:** `--test-threads=<N>` (default CI: 64), `--run-all-tests`, `--retest`, `--junit <file>`
 
-## Code Quality & CI
+## Code Style & Quality
 
-### Format & Lint (REQUIRED before commit)
+### C++ Style (MANDATORY - clang-format-18 required)
 ```bash
-# C++ formatting (MANDATORY)
-clang-format-18 -i file.cpp file.h
+# Format all modified C++ files before commit
+clang-format-18 -i $(git diff --name-only --diff-filter=AM | grep -E '\.(cpp|h)$')
+clang-format-18 --dry-run -Werror file.cpp  # Verify without modifying
+```
+
+**Naming Conventions** (from .clang-tidy):
+- Classes/Structs: `TCamelCase`, Interfaces: `ICamelCase`, Enums: `ECamelCase` (constants: `UPPER_CASE`)
+- Namespaces: `NCamelCase`, Functions: `CamelCase`, Variables: `camelBack`, Macros: `UPPER_CASE`
 
-# Enable git hooks (checks trailing whitespace)
-git config core.hooksPath .githooks
+**Style Rules**: 80 columns max, 4-space indent, custom braces (after class/function/struct, not namespace)
 
-# Pre-commit checks
-pre-commit run --all-files
+### Linting & Pre-Commit (REQUIRED)
+```bash
+git config core.hooksPath .githooks           # Enable hooks (checks whitespace)
+pre-commit run --all-files                    # Validate YAML, whitespace, newlines
+./ya make --test-type=clang_tidy -t <target>  # C++ linting
+./ya make --test-type=flake8,black -t cloud/  # Python
+./ya make --test-type=gofmt -t cloud/disk_manager/  # Go
 ```
 
-### CI Workflows
+### Code Review Checklist (verify before PR)
+- [ ] clang-format-18 applied to all C++ files
+- [ ] Naming follows conventions (T/I/E/N prefixes, camelBack)
+- [ ] No trailing whitespace (`git diff --check` passes)
+- [ ] Line length ≤80 columns
+- [ ] Tests added/updated and passing (small/medium: `./ya make -t --test-size=small,medium`)
+- [ ] Builds without warnings
+- [ ] No clang-tidy warnings in modified code
+- [ ] Complex logic has comments, no unexplained commented-out code
+
+## CI Workflows
 **Main PR:** `.github/workflows/pr.yaml` - Triggers on PR to `main` (skips docs/examples/md files). Requires org membership or `ok-to-test` label for external contributors.
 
 **Build/Test:** `.github/workflows/build_and_test_ya.yaml` - Targets: `cloud/blockstore/apps/`, `cloud/filestore/apps/`, `cloud/disk_manager/`, `cloud/tasks/`, `cloud/storage/`. Default tests: `unittest,clang_tidy,gtest,py3test,py2test,pytest,flake8,black,go_test,gofmt`. Sizes: `small,medium,large`. Preset: `relwithdebinfo`.
@@ -120,11 +140,19 @@ sudo ./6-attach_disk.sh --disk-id vol0 -d /dev/nbd0
 
 ## Agent Workflow
 
-1. **Format C++ with clang-format-18** (mandatory)
-2. **Run pre-commit checks** (`git diff --check` or hooks)
-3. **Build incrementally:** `./ya make cloud/blockstore/apps/server` to catch errors early
-4. **Test changed components:** `./ya make -t --test-size=small,medium cloud/blockstore/libs/service`
-5. **Verify locally** using `example/` scripts for runtime changes
-6. **Trust these instructions** - only search if incomplete/incorrect
+**Making changes with code style/review focus:**
+
+1. **Before coding:** Review existing code style in target area, check related tests
+2. **While coding:** Follow naming (TCamelCase/ICamelCase/camelBack), keep ≤80 cols, comment complex logic
+3. **Before commit (MANDATORY):**
+   ```bash
+   clang-format-18 -i $(git diff --name-only --diff-filter=AM | grep -E '\.(cpp|h)$')
+   git diff --check  # No trailing whitespace
+   ./ya make <target>  # Build without warnings
+   ./ya make -t --test-size=small,medium --test-type=unittest,clang_tidy <target>
+   ```
+4. **Self-review:** Check naming conventions, no debug/commented code, tests cover edge cases
+5. **Verify checklist:** Format ✓, naming ✓, whitespace ✓, tests ✓, builds ✓, linting ✓
+6. **Local testing:** Use `example/` scripts for runtime verification if needed
 
 **Quick Ref:** Build all: `./ya make cloud/blockstore/buildall -r` | Test: `./ya make -t cloud/blockstore/` | Format: `clang-format-18 -i file.cpp` | Sanitizer: `./ya make --sanitize=address <target>` | Docs: `doc/REPOSITORY_STRUCTURE.md`

From df3a18a7f6c4c9356da6417214384bc705781268 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 24 Nov 2025 15:47:08 +0000
Subject: [PATCH 8/8] Clarify checklist items based on code review feedback

Co-authored-by: jkuradobery <149376659+jkuradobery@users.noreply.github.com>
---
 .github/copilot-instructions.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 1624c4f815b..0feee13ff8e 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -78,10 +78,10 @@ pre-commit run --all-files                    # Validate YAML, whitespace, newli
 - [ ] Naming follows conventions (T/I/E/N prefixes, camelBack)
 - [ ] No trailing whitespace (`git diff --check` passes)
 - [ ] Line length ≤80 columns
-- [ ] Tests added/updated and passing (small/medium: `./ya make -t --test-size=small,medium`)
+- [ ] Tests added/updated and passing: `./ya make -t --test-size=small,medium <target>`
 - [ ] Builds without warnings
 - [ ] No clang-tidy warnings in modified code
-- [ ] Complex logic has comments, no unexplained commented-out code
+- [ ] Complex logic has comments, no debug prints or unexplained commented-out code
 
 ## CI Workflows
 **Main PR:** `.github/workflows/pr.yaml` - Triggers on PR to `main` (skips docs/examples/md files). Requires org membership or `ok-to-test` label for external contributors.
@@ -151,7 +151,7 @@ sudo ./6-attach_disk.sh --disk-id vol0 -d /dev/nbd0
    ./ya make <target>  # Build without warnings
    ./ya make -t --test-size=small,medium --test-type=unittest,clang_tidy <target>
    ```
-4. **Self-review:** Check naming conventions, no debug/commented code, tests cover edge cases
+4. **Self-review:** Check naming conventions, no debug prints/unexplained commented code, tests cover edge cases
 5. **Verify checklist:** Format ✓, naming ✓, whitespace ✓, tests ✓, builds ✓, linting ✓
 6. **Local testing:** Use `example/` scripts for runtime verification if needed