update: update the dev-docs for AI agent

dev-docs/coding-guidelines.md

@@ -0,0 +1,51 @@
+# Coding Guidelines
+
+## General style
+
+- Prefer straightforward Python
+- Use type hints
+- Keep functions small and focused
+- Add docstrings to public functions and classes
+- Avoid overengineering
+- Prefer composition over deep inheritance
+
+## Error handling
+
+- Fail clearly
+- Provide helpful error messages
+- Distinguish user-facing CLI errors from internal exceptions
+- Avoid silently swallowing errors
+
+## Logging
+
+- Use structured and informative logging where useful
+- Avoid noisy logs in normal CLI output
+- Keep machine-readable command output clean when `--json` is used
+
+## File operations
+
+- Be careful with moves, copies, and overwrites
+- Prefer atomic writes for JSON files when possible
+- Never corrupt existing metadata due to partial writes
+
+## Idempotence
+
+Where possible, commands should behave safely when run multiple times.
+
+Examples:
+- re-importing the same file should detect duplicates
+- `render-summary` should be repeatable
+- `reindex` should be safe to rerun
+
+## Testing
+
+Add tests for:
+- path layout logic
+- metadata read/write behavior
+- duplicate detection
+- reindex behavior
+- summary rendering
+- search behavior
+- CLI output contracts for core commands
+
+Prefer unit tests for core logic and targeted integration tests for CLI behavior.