Agentic Coding

Based on the research from ETH Zurich and Vercel, AGENTS.md files help agents handle non-standard coding practices and undocumented features but add over 20% context cost without improving general task success. Keep files under 200 lines by including only what the agent cannot learn from code: project commands, non-standard conventions, environment quirks, "don't" rules, and definitions of "done". Leave out project summaries, standard language conventions, and long documentation. Test new rules after mistakes rather than adding them preemptively, and use /init to generate a draft then remove descriptions. For Claude Code specifically, use CLAUDE.md with the single line @AGENTS.md to share instructions across tools, and move occasional instructions to subfolders, rule files, skills, or hooks to keep the main file lean and focused.

Claude Code is an agentic coding tool that reads files, runs commands, edits code, and iterates on errors based on plain English descriptions. The guide emphasizes creating a CLAUDE.md file in your project root as standing instructions that Claude Code reads at the start of every session—this should specify tools to use (like uv for Python), how to run tests, and project conventions. It also mentions that Claude Code reads AGENTS.md when no CLAUDE.md exists. For effective agentic workflows, keep instructions short and factual, include concrete project-wide commands, and use skills or subagents for reusable procedures. The guide recommends giving Claude Code specific, concrete instructions with goals and constraints rather than abstract requests, maintaining focused sessions to manage token usage and context window limits, and always reviewing diffs before approving changes since the agent can make common mistakes like choosing wrong libraries or hallucinating APIs.

Moving from a GenAI proof-of-concept to production-grade agentic systems requires structured organization beyond just good prompts. Key practices include: establishing a folder structure with separated workflows, guardrails, and observability modules; creating a lean CLAUDE.md file under 200 lines that documents non-obvious patterns like Zod validation and naming conventions; using path-scoped rules in .claude/rules/ to keep context windows clean; implementing PreToolUse as a security gate to block dangerous commands; and specializing subagenents with isolated permissions. A 20-person AI-native company recommends organizing the .claude/ directory with skills/ for single-task handlers, agents/ for longer workflows, commands/ for multi-skill operations, hooks/ for role-based access control, and rules/ for file-specific behavior, paired with a root CLAUDE.md that contextualizes the repo, INDEX.md for content discovery, wiki/ for company knowledge, and clients/ for client-specific information. Production AI agents also benefit from clear project structures separating agent logic, tools, models, prompts, and utilities into distinct modules rather than monolithic files, with dedicated sections for API exposure, testing, data management, and logging for maintainability and debuggability at scale.