environment-design

name	environment-design
description	Optimize the agent's working environment (project structure, config files, tool availability) to make productive actions obvious and error-prone patterns invisible. Use when setting up a project, auditing a codebase, or reducing friction in development workflows.

You are an AI agent applying the Environment Design framework from Atomic Habits by James Clear to your operational workspace. Use this skill to engineer the project structure, configuration, and tooling so that the RIGHT actions are frictionless and the WRONG actions require deliberate effort.

Core Principle

"Motivation is overrated; environment often matters more." An agent doesn't need better prompting — it needs a better-structured workspace. When the project layout, configs, and tool integrations are optimized, productive behavior becomes the path of least resistance.

The Two Laws of Environment Design (Agent Version)

1st Law: Make It Obvious (Promote Good Patterns)

Surface critical information and tools so they are immediately accessible:

• Move important config files to the project root (not buried 3 levels deep)
• Create a README.md with clear setup instructions so the agent finds context instantly
• Use descriptive file names and directory structures (not [poorly_named_file])
• Place .env.example alongside .env so required variables are obvious
• Add CONTRIBUTING.md to surface coding conventions

2nd Law (Inversion): Make It Invisible (Suppress Bad Patterns)

Hide or gate dangerous operations so they require deliberate effort:

• Add .gitignore to prevent committing secrets, build artifacts, and temp files
• Use pre-commit hooks to block malformed commits automatically
• Configure [linter]/[formatter] to auto-reject anti-patterns before they enter the codebase
• Lock production branch with required reviews — making direct pushes impossible
• Remove dead code and unused dependencies to reduce cognitive noise

The Environment Audit

Step 1: Scan the Workspace

Using list_dir, find_by_name, and grep_search, audit the current project for:

• Exposed secrets (.env files, API keys in source)
• Missing documentation (no README, no setup guide)
• Clutter (temp files, [dependency_folders] checked in, [compiled_binaries] scattered)
• Broken conventions (mixed naming styles, inconsistent folder structure)

Step 2: Apply Friction Engineering

• Promotion (reduce steps for good behavior): Add scripts to [dependency_manifest] so running tests is [test_command], not a 3-step manual process.
• Reduction (increase steps for bad behavior): Add branch protection so deploying to production is a multi-step, reviewed process — not a single git push.

Step 3: Create Context Separation

Each directory should have a single purpose:

• /src for source code — not mixed with configs
• /tests for test files — not scattered across source directories
• /docs for documentation — not inline comments only
• /scripts for automation — not embedded in READMEs

Agent-Native Examples

Friction Problem	Environment Fix	Effect
Agent can't find config	Move [config_file] to project root	Instant context
Tests require manual setup	Add [setup_script]	One-command testing
Secrets in source code	Add .gitignore + secret scanning	Prevent leaks
Inconsistent code style	Add [formatter_config] + pre-commit hook	Auto-enforcement
Unused imports everywhere	Configure auto-remove in linter	Clean codebase

Anti-patterns to Watch For

• Relying on "agent discipline" instead of tooling enforcement
• Over-engineering the structure before writing any code
• Mixing concerns in directories (tests + source + configs in one folder)
• Not updating .gitignore after adding new tools/frameworks

Output

When applying this skill, produce:

1. An audit of current friction points in the workspace
2. A list of "promotion" changes (make good patterns easier)
3. A list of "reduction" changes (make bad patterns harder)
4. The specific file/config changes to implement