Agent Manifests: Structure & Best Practices

• Agent manifests are formal, structured documents detailing autonomous agent context, identity, and operational instructions.
• Empirical analyses of 253 manifests reveal standardized shallow hierarchies and key content areas such as build commands, implementation details, and architecture components.
• Iterative refinement and adherence to best practices in manifest creation enhance automated code generation and effective task decomposition.

Agent manifests are formal, structured artifacts—typically documents or configuration files—that encode the context, identity, operational rules, and intended behaviors of autonomous agents within complex systems. In the agentic coding ecosystem, these manifests (e.g., Claude.md) serve as the interface through which agents interpret project objectives, execution procedures, and architectural requirements, thus enabling both automated task decomposition and minimal-human-involvement code generation. A recent empirical analysis of 253 Claude.md manifests across 242 repositories reveals canonical structural and content conventions that reflect current best practices, usage trends, and remaining challenges in manifest creation and maintenance (Chatlatanagulchai et al., 18 Sep 2025).

1. Structural Patterns in Agentic Coding Manifests

The typical agent manifest follows a shallow hierarchical structure. The overwhelming majority feature a single H1 (main topic) header per document, with a median of 5 H2 (broad aspect) subsections and 9 H3 (detailed instruction) levels; deeper nesting (H4–H6) is rare (H4: 37, H5: 5, H6: 1 occurrence among 253 files). This structural consistency promotes both human readability and parsing efficiency for coding agents. The prevailing pattern:

$$\begin{array}{ll} \textbf{H1:} & \text{Main Topic}\ \textbf{H2:} & \text{Broad aspects (e.g., Overview, Coding Standards, Instructions)}\ \textbf{H3:} & \text{Details (e.g., Testing, Implementation specifics)}\ \end{array}$$

A plausible implication is that the shallow hierarchy and dense but levelled content organization simplify the agent's information extraction and operationalization process.

2. Content Taxonomy and Prevalence

The content of analyzed manifests is heavily oriented toward actionable and technical directives. The dominant content types include:

• Build and Run commands: Present in 77.1% of documents, these sections detail the steps—typically shell commands—for compilation, setup, and execution.
• Implementation Details: Found in 71.9% of manifests, these capture coding guidance, implementation instructions, and pattern specifications.
• Architecture: 64.8% include high-level system diagrams, data flow or component descriptions.
• Testing Procedures: 60.5% specify testing sequence, coverage, or relevant scripts.
• AI Integration: Incorporated in 15.4%, focusing on agent-specific setup or tool invocation.
• System Overview, Configuration, DevOps, and Project Management: Appear in varying (lower) frequencies.

The following table summarizes the prevalence of content categories:

Category	Label	Description	%
General	System Overview	General project overview, features	48.2
	AI Integration	Agentic tool-specific instructions	15.4
	Doc. Refs	Auxiliary documentation references	13.8
Implementation	Architecture	Structural and design information	64.8
	Impl. Details	Coding methods and implementation guidance	71.9
Build	Build and Run	Build commands, run scripts	77.1
	Testing	Test execution strategies	60.5
	Conf. Env.	Environment/system config instructions	26.5
	DevOps	Deployment/operational processes	9.5
Management	Dev. Process	Workflow, versioning, and collaboration logistics	37.2
	Proj. Mgmt.	Project planning, organizational schemes	11.1
Quality	Maintenance	Bug fixing and system upkeep	19.8
	Performance	QA and optimization details	12.7
	Security	Security guidance and best practices	8.7
	UI/UX	Interface and user experience considerations	8.3

These statistics demonstrate that agent manifests are systematically focused on ensuring that an agent can robustly execute, test, and comprehend its operational role, while non-functional and ancillary concerns (security, UI/UX, performance) are less prevalent.

3. Challenges in Manifest Creation and Maintenance

Key difficulties identified in practice include:

• Absence of Reference Documentation: Developers lack standardized, comprehensive guidelines for formulating agent manifests, leading to an ad hoc, trial-and-error approach across repositories.
• Context Capturing Complexity: Manifests must balance explicit, actionable procedures (e.g., commands and implementation details) with high-level project and role context (e.g., architecture, AI integrations), which complicates design.
• Evolving Project Requirements: As software evolves, manifests frequently become stale or misaligned with the codebase, impairing agent functionality and necessitating ongoing maintenance.

The paper suggests that adopting a predictable, shallow structure; explicit separation of operational and contextual details; and regular document revision can partially mitigate these challenges.

4. Empirical Documentation Trends

Analysis over a sizable set of open-source repositories quantifies typical manifest design and deployment:

• Header usage: Median of 1 H1, 5 H2, 9 H3 per manifest.
• Content overlap: Most manifests prioritize “Build and Run,” implementation specifications, and architectural aspects.
• Technical focus: Directly actionable and highly operational sections, such as scripts and command sequences, dominate.
• Rarity of extended hierarchies: Very few manifests exploit H4–H6 header depth, reflecting an industry-wide consensus or practical constraint.

This suggests that the function of agent manifests is pragmatically anchored in operationalizing project knowledge for code-generating agents rather than aspiring to full software specification documentation.

5. Design Implications for Agent-Driven Development

The findings support several concrete guidelines for effective manifest creation:

• Adopt a standardized, shallow hierarchy: A stable structure—a single H1, around 5 H2, and approximately 9 H3—maximizes clarity and agent-accessibility.
• Prioritize operational clarity: Ensure sequences for “Build and Run,” as well as coding and architectural guidance, are explicit; these dominate agent use and interpretation.
• Distinguish between technical and contextual segments: Dedicated sections for system overviews and AI integration facilitate correct role and context modeling by agentic tools.
• Plan for iterative refinement: Regularly update manifests in tandem with code changes to avoid knowledge decay, enabling persistent agent coherence.
• Use statistical benchmarks from empirical data: Quantitative trends in header and content prevalence can inform manifest scaffolding for future projects.

6. Agent Manifest Functionality and Limitations

Agent manifests, as observed in this paper, consistently fulfill a dual function: providing actionable, granular execution instructions and establishing sufficient context for agentic role alignment. Their shallow structure and focus on implementation and operation enable LLM-based agents to autonomously break down high-level tasks and execute code reliably. However, the infrequent inclusion of security, performance, or UI/UX guidelines reveals a potential misalignment with full-spectrum software best practices. A plausible implication is that, while current manifest conventions accelerate agent operationalization, additional work is needed to ensure broader coverage as agent-driven systems become more complex and safety- or quality-critical.

7. Conclusions and Best Practices

Agentic coding manifests, especially as instantiated in Claude.md and similar files, are marked by shallow, operationally focused hierarchies and a technical, action-centric corpus. Developers are advised to build on the identified conventions and quantitative patterns, segmenting instructions by function (e.g., build, implement, test) and context (overview, architecture, AI integration), and iteratively maintaining manifests as projects evolve. These practices not only support effective human-agent collaboration but also underpin the reliable and autonomous functioning of next-generation coding agents (Chatlatanagulchai et al., 18 Sep 2025).