AGENTS.md

1# Files Development Guidelines
2 
3This project is a C#/.NET WinUI 3 desktop app; an alternative to File Explorer.
4 
5- Protect context usage. Any command with unknown or potentially large output must be capped. Prefer targeted commands such as `rg`, `Get-Content -TotalCount`, `Select-Object -First`, or focused `git diff -- <path>`; for example, `COMMAND 2>&1 | Select-Object -First 200`. If a line cap is still too noisy, narrow the query instead of dumping full output.
6- Always follow `.editorconfig`
7- Keep changed text files in CRLF line endings
8- Keep comments concise and useful. Do not add comments that restate obvious code.
9- Never read entire generated files in `bin` or `obj` unless the generated source is directly needed.
10- Prefer targeted search over full file reads.
11- Touch only what you must. Clean up only files you created or changed for the task.
12- Treat file operations, shell integration, drag/drop, preview handlers, archive actions, settings persistence, and localization as high-risk areas.
13- For Win32, COM, Shell, clipboard, hotkey, and file operation interop, prefer `src/Files.App.CsWin32`, `NativeMethods.txt`, and existing wrappers/helpers.
14- Avoid ad hoc P/Invoke declarations when CsWin32 or existing interop code can cover the API.
15- Do not edit generated CsWin32 output directly. Update source declarations, wrappers, or generator inputs instead.
16- For UI work, use existing XAML resources, controls, converters, commands, and localization patterns. Avoid one-off styles or hard-coded user-visible strings.
17- Start by identifying the smallest relevant project, feature area, and files for the task.
18- Read nearby code before adding new abstractions. Prefer existing WinUI, MVVM, service, command, and storage patterns.
19- Keep implementation scoped to the requested behavior. Avoid opportunistic refactors, formatting churn, dependency updates, and generated file edits.
20- Treat tool output as evidence. When behavior changes, run the focused build that can prove it and report anything left unverified.
21 
22## Codebase Structure
23 
24```text
25/src
26├── Files.App                    Main WinUI app
27├── Files.App.Controls           Shared app controls
28├── Files.App.Storage            App storage abstractions and implementations
29├── Files.App.CsWin32            Generated/native Win32 interop project
30├── Files.App.BackgroundTasks    Background task project
31├── Files.App.Server             App service/server project
32├── Files.Core.SourceGenerator   Roslyn source generators and analyzers
33├── Files.Core.Storage           Core storage abstractions
34└── Files.Shared                 Shared attributes, extensions, and common code
35```
36 
37```text
38/tests
39├── Files.App.UITests
40├── Files.App.UnitTests
41└── Files.InteractionTests
42```
43 
44## Build
45 
46Prefer explicit platform/configuration builds.
47Unless the task is specifically about resolving or inspecting warnings, add `-v:quiet -clp:ErrorsOnly` to `msbuild` commands so the log proves success or shows only actionable errors.
48 
49```powershell
50msbuild -restore Files.slnx -p:Configuration=Debug -p:Platform=x64 -v:quiet -clp:ErrorsOnly
51```
52 
53If `msbuild` isn't available in the current shell, run it from Visual Studio Developer PowerShell. Match `-arch`, `-host_arch`, and `-p:Platform` to the platform you're verifying; use `x64` for x64 work and `arm64` for ARM64 work.
54 
55```powershell
56pwsh.exe -NoProfile -Command "& {
57  Import-Module 'C:\Program Files\Microsoft Visual Studio\18\Professional\Common7\Tools\Microsoft.VisualStudio.DevShell.dll'
58  Enter-VsDevShell 1ba2cc4e -SkipAutomaticLocation -DevCmdArguments '-arch=x64 -host_arch=x64'
59  msbuild -restore src/Files.App/Files.App.csproj -p:Configuration=Debug -p:Platform=x64 -v:quiet -clp:ErrorsOnly
60}"
61```
62 
63For focused C# work, build the affected project first.
64Do not run build commands in parallel.
65 
66```powershell
67msbuild -restore src/Files.Shared/Files.Shared.csproj -p:Configuration=Debug -p:Platform=x64 -v:quiet -clp:ErrorsOnly
68msbuild -restore src/Files.Core.SourceGenerator/Files.Core.SourceGenerator.csproj -p:Configuration=Debug -p:Platform=x64 -v:quiet -clp:ErrorsOnly
69msbuild -restore src/Files.App/Files.App.csproj -p:Configuration=Debug -p:Platform=x64 -v:quiet -clp:ErrorsOnly
70```
71 
72## Test
73 
74We currently don't have a suitable set of tests for AI agents. Just make sure that the builds succeed.
75 
76## Commit & Push
77 
78When asked to commit, run these commands beforehand:
79 
80```powershell
81git status --short
82git diff --check
83```
84 
85Do not revert unrelated user changes. Stage only files that belong to the requested change.
86 
87Use concise commit messages that describe the behavior change, for example:
88 
89```text
90Add source-generated settings storage
91```
92 
93## Open a PR
94 
95When asked to open a PR, use a short PR title that names the behavior, not the implementation mechanics only, and prepend the PR type:
96 
97- "Fix": use this prefix when the linked issue is a bug
98- "Feature": use this prefix when the linked issue is a feature request
99- "Code Quality": anything else
100 
101The repository maintainers draft release notes based on these PR types: only fixes and feature requests are listed.
102 
103Good examples:
104 
105```text
106Fix: Fixed an issue where thumbnails wouldn't refresh when a file was updated
107Feature: Add support for previewing AVI files in the Preview Pane
108Code Quality: Add source-generated settings serialization
109```
110 
111For the PR body, follow `./.github/PULL_REQUEST_TEMPLATE.md`.
112