diff --git a/packages/AGENTS.md b/packages/AGENTS.md
new file mode 100644
index 000000000000..64e0baab7bc7
--- /dev/null
+++ b/packages/AGENTS.md
@@ -0,0 +1,38 @@
+## Project Structure & Module Organization
+
+The repository follows a modular structure with clear separation between public APIs and internal implementation details.
+
+## Build, Test, and Development Commands
+
+- Build commands and test procedures should be documented as they are established
+- Development workflow commands should be added as the repository evolves
+
+## Coding Style & Naming Conventions
+
+1. Use TypeScript for type-safe code
+2. Follow existing naming conventions in each module
+3. Use descriptive variable and function names
+4. Add type definitions to formalize contracts between packages
+
+## Architecture & Design Patterns
+
+1. Establish explicit service definition boundaries for all public/external APIs by creating well-defined interface contracts, clear module exports, and separation between public API surfaces and internal implementation details. This pattern manifests through: (1) Dedicated API modules that expose only intended public functions, (2) Clear separation between internal utilities and external-facing services, (3) Consistent export patterns that signal API stability, (4) Type definitions that formalize the contract between packages, and (5) Structured service boundaries in codemods, AST manipulation, and core design system components. Files like design-system.ts, apply.ts, and ast.ts serve as public API entry points, while internal utilities like default-map.ts provide supporting infrastructure with controlled visibility.
+
+## Testing Guidelines
+
+1. Write unit tests for business logic
+2. Include integration tests for critical functionality
+3. Aim for meaningful test coverage of public APIs
+
+## Commit & Pull Request Guidelines
+
+1. Write clear, descriptive commit messages
+2. Reference issue numbers in commits when applicable
+3. Keep PRs focused and reviewable
+4. Ensure tests pass before requesting review
+
+## Security & Configuration Tips
+
+1. Follow security best practices for dependency management
+2. Keep configuration separate from code
+3. Document any security-relevant decisions
\ No newline at end of file