C_SHARP_SKILLS/.ai/skills/09-files-streams-serialization.md

Skill 09 - Files, Streams, Encoding, and Serialization

Filesystem Rules

• Use Path.Combine or Path.Join; do not concatenate paths manually.
• Consider case sensitivity and path separator differences across Windows and Linux.
• Validate and normalize user-supplied paths to prevent traversal attacks.
• Use Directory.EnumerateFiles for large directory trees.
• Dispose file handles and streams with using or await using.

Stream Rules

• Use streams for large data instead of loading everything into memory.
• Use async stream APIs for I/O in web/server apps.
• Reset stream position when re-reading.
• Do not assume a stream is seekable unless you check.

Encoding Rules

• Specify encoding explicitly for file formats and protocols.
• Prefer UTF-8 for new text files and APIs.
• Do not mix bytes and characters without explicit conversion.

Serialization Rules

• Prefer System.Text.Json for JSON.
• Use XML only when required by interoperability or legacy systems.
• Do not use insecure binary serialization patterns.
• Treat deserialized data as untrusted input.
• Use DTOs for external contracts rather than exposing domain or EF entities directly.
• Version serialized contracts carefully.

JSON Rules

• Configure naming policy intentionally.
• Use source generation for performance-sensitive serialization.
• Avoid serializing cycles unless explicitly configured and tested.